From: Sean Russell <ser@...>
Date: 2002-05-22T00:14:05+09:00
Subject: Re: [RDoc etc] automatic documentation: using tests in addition to / instead of comments

Man, how did I miss this thread?

Dave Thomas wrote:

> Say you're looking at method 'fred' in RDoc. In the documentation
> there'll be hyperlinks to 'Examples of this in action'. Click it, and
> up will pop the test methods.

I haven't finished reading the entire thread, but I'll throw in my opinion.

Unit tests are not contracts, per se, as contracts appear in other 
languages.  If you want inline contracts, I suggest that we think of 
another syntax for describing them, and not using runit or Test::Unit.  
Contracts guarantee that a method will behave in a stated way, but they are 
not necessarily examples of usage.  For documentation, examples are needed.  
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.

Therefore, I'd like to keep the unit tests and the application code 
separate.  One reason is that copious documentation can make the source as 
difficult to edit as no documentation.  Another is that those bytes will 
get installed with the application on the end-user machine, and this may 
not be appropriate, and will certainly in most cases be a waste of space.  
Yet another is the argument of poor encapsulation and increased difficulty 
of working with the unit tests.

I much prefer the idea of passing an argument telling rdoc where the unit 
tests are, and allowing the users to point to the appropriate unit tests in 
the source documentation.  This is more tedious for the documentation 
author, but without embedding the unit tests within the source 
documentation, there isn't another way of rdoc telling which tests belong 
to which method -- although it would be possible for rdoc to "index" the 
unit test methods and add a reference in the method API doc for every unit 
test that references that method.

Additionally, I prefer having a separate frame for displaying the unit test 
example, rather than inline.  In the common case, the inlined code will get 
in the way of browsing the APIs, since it'll add significant noise.

This is basically the original proposal I made to you on this matter a 
couple of weeks ago.  I've somehow missed the original message that started 
this discussion in the usenet group, so I don't know if you quoted that or 
not.

--- SER