From: Tobias Reif <tobiasreif@...>
Date: 2002-05-22T01:20:04+09:00
Subject: Re: [RDoc etc] automatic documentation: using tests in addition to / instead of comments

Sean Russell wrote:


> Contracts guarantee that a method will behave in a stated way, but they are 
> not necessarily examples of usage.  For documentation, examples are needed.


The inline tests would be usage examples that can be run automatically 
for testing, and can be used by RDoc et al to extract documentation.

  
> Unit tests are a cross between example usage and contracts, but since they 
> are more than contracts, I don't believe that they are appropriate for 
> inlining in the source documentation.


Those that are runnable examples can be inlined and used for 
documentation, and the rest of the tests stays in separate files and 
gets ignored by RDoc.


> I much prefer the idea of passing an argument telling rdoc where the unit 
> tests are,


Perhaps both ways could be implemented, as alternative options.


> In the common case, the inlined code will get 
> in the way of browsing the APIs, since it'll add significant noise.


I don't think the noise would increase.
1. All tests that aren't usage examples would still reside in separate 
files.
2. All inline tests would merely replace comment blocks containing usage 
examples, thus taking no more space; but they would be runnable in an 
automated way. Often there would be comments as before, and external 
test files as befoer, only the usage example comments would be replaced 
with actual code.

I like this whole thing more and more; can't wait to work with this 
feature in RDoc ... :)

Tobi

-- 
http://www.pinkjuice.com/