"Dave Whipp" <[EMAIL PROTECTED]> writes:
> "Chromatic" <[EMAIL PROTECTED]> wrote:
>> Advantages of inline tests:
>> - close to the documentation
>> - one place to update
>> - harder for people to update docs without finding code
>
> Plus, it gives us a mechanism to validate example-code
> within documents
>
>> Disadvantages:
>> - doc tools must skip tests normally
>> - pure-doc patches are harder
>> - some tests (bugs, regressions) don't naturally fit in docs
>> - makes docs much larger
>> - adds an extra step to extract tests before running them
>> - adds weight to installed documents (or they must be extracted)
>
> These seem to be reasonable arguments: though issues of file-size and the
> need for extraction seem a bit weak. Oh, and bugs do belong in documents:
> "erata".
>
> The majority of tests do not belong in documents, for the simple reason that
> they are implementation-centric, not user-centric. But then, in perl, every
> file can contain POD, so even external-test files can be documents
> (documents that are not part ofthe perl6 documentation project).
There is, of course, nothing to stop us doing both. Where possible one
should code examples in documents in such a way that they can be used
as tests, but I should have thought that good examples for
documentation will be peppered with ... and/or assume largish
'fixtures' that would interfere with the document's didactic
purpose. For instance, when you're illustrating the Given/when syntax
you'd give an example like:
given $foo {
when .bar { ... } # $foo.bar returns true
when "literal" { ... } # $foo eq 'literal'
when 10 { ... } # $foo == 10
when @ary { ... } # grep /$foo =~ $_/, @ary
}
That chunk of code is (marginally) useful as an example, as a test it
has almost no utility. One could/should test that it parses correctly,
but, frankly, that's of more benefit to the test author than it is to
those making perl6 work.
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.
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.
--
Piers
"It is a truth universally acknowledged that a language in
possession of a rich syntax must be in need of a rewrite."
-- Jane Austen?
