From: Mike Stok <mike@...>
Date: 2002-05-21T10:33:46+09:00
Subject: Re: [RDoc etc] automatic documentation: using tests in addition to / instead of comments

In article <m23cwndl8g.fsf@zip.local.thomases.com>, Dave Thomas wrote:

> [...] When rdoc'd,
> the test code gets extracted and used as class-level documentation.

Are tests intended to be used that way?  Most of the tests I write after the
initial "this is how it ought to work" test(s) are often fragments of code
which make little sense - they are cut down frgments of other programs 
which tickled code flaws.

One suggestion in the Perl world was a:

  =for example

  code

  =cut

style of documentation markup where the test suite could make sure that the
examples in the documentation would at least run.  (There was room for
a prefix area to allow setup which wouldn't end up in the docs too.)

Maybe there is a place for the tests writen as part of the code's design in
the documentation.   This mechanism gives people the freedom to have
them there, and presumably still have a separate file for the "ugly"
test cases which gather as the code is stressed in unforeseen ways?

Mike

-- 
mike@stok.co.uk                    |           The "`Stok' disclaimers" apply.
http://www.stok.co.uk/~mike/       | GPG PGP Key      1024D/059913DA 
mike@exegenix.com                  | Fingerprint      0570 71CD 6790 7C28 3D60
http://www.exegenix.com/           |                  75D2 9EC4 C1C0 0599 13DA