Re: Docs Testing Format

Piers Cawley wrote:

> I'm not arguing that the unit tests themselves shouldn't carry
> documentation, but that documentation (if there is any) should be
> aimed at the perl6 developer. 

Depends what you mean by "perl6 developer": is that the internals 
people, or the lucky user?

Unit tests should be aimed at internals people: it would obviously be 
nice to have a few comments/POD in there.

Our focus should be the user. There are really two deliverables: 
documentation that details how use the language; and a "language 
reference manual": which pins down every detail in an unambiguous 
manner, but not necessarily very readable. This reference could just be 
the set of tests; but they'd have to be sufficiently readable that an 
outsider could decode them without an Enigma machine.

> BTW, from my point of view, the tests should be authoratative. If the
> tests and the docs disagree then, unless someone in authority rules
> otherwise, the test wins.
>