From: benny <listen@...>
Date: 2004-11-26T07:02:58+09:00
Subject: Re: [RDOC] Using unit-tests as examples for a documentation

Dave Thomas wrote:

> 
> On Nov 25, 2004, at 15:32, benny wrote:
> 
>> Now the idea: Why not use the examples in the unit-tests (at least the
>> "positive ones") as link to a popup window "examples" in the
>> HTML-documentation created by rdoc?
> 
> This has been raised before. 
sorry, I didn't notice that. Don't want to bore the list.

> The problem is that it's hard to work out 
> which tests test which methods: method naming conventions would help,
> but even so you quite often have three test methods testing one
> production method.
but that could be made by a really simple convention:
the name of each test method for method "foo" should be

test_foo_individual_name

Anyway this would be an *option*, i.e. test-methods not following that
convention would silently slip away (which might also be a useful feature).

> 
> An alternative might be to embed the UTs in the comment for the method,
> and then have TestUnit extract and run them automatically. I personally
> quite like that approach, although it would need some special markup
> that RDoc doesn't yet support.

I don't think it is good to embed the testing methods into the
documentation. Think of packaging your sources: it might be useful to
separate the tests from the code for smaller packages. the user when
generating the documentation would then not have the examples in the docs
but the developer might offer them on the online docs.

also think of a replacement for a set of given classes methods. you might
want to use the same tests on different development branches to ensure the
compatibility. for using rdoc in this case you start it in the
corresponding branch and make a simple symlink named "test" to the
unit-test directories.

regards, 
benny


> 
> 
> Cheers
> 
> Dave