From: Paul Brannan <pbrannan@...>
Date: 2002-05-22T00:56:54+09:00
Subject: Re: [RDoc etc] automatic documentation: using tests in addition to / instead of comments

On Wed, May 22, 2002 at 12:14:05AM +0900, Sean Russell wrote:
> 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.

OTOH, it would be nice if one could test the examples, to ensure that
the documentation is up-to-date.

Paul