"Gavin Sinclair" <gsinclair / soyabean.com.au> wrote in message news:<64119.203.185.214.34.1075684452.squirrel / webmail.imagineis.com>...
> [Charles Comstock:]
> 
> I fully agree on all counts.  I'll just mention, though, that RDoc
> actually encourages introductory/usage/example documentation, *so long as
> the developer wants to write it*.  For example:
> 

An idea I was wondering was if it might be possible to link unit tests
and RDoc.

It would work like this:

- The developer creates unit tests for their class, starting with the
simplest usages and then testing each facet of the code with unit
tests.

- There may be some extra, optional, notation for expressing how a
test would appear in the documentation.  For example, a test may be
marked to be included in the main body of the documentatation, while
others are linked in a separate document.  You could also categorise
the unit tests, and add other meta language.

- RDoc then processes these unit tests, formatting and indexing them,
and includes them with the final documentation.

I think this approach could make it easier for class writers to
produce extensive examples whithout much additional work.