From: Aredridel <aredridel@...>
Date: 2004-02-09T16:09:27+09:00
Subject: Re: Documentation approaches (was: Python 25 times as popular as Ruby !?)

> 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.

That's an excellent idea -- it would probably promote init testing as
well as documentation.  That's a very good thing.

> - 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.

I agree. I just jumped into unit testing, and rdoc is next on my list of
tools to learn. (I'd really love to help with the ruby-doc projects,
because the docs -are- what made me use PHP for so long. It's truly a
language for people with no memory -- the docs are great, and everything
else guessable.  Terribly easy to write bad code in, but that just
encourages one-off scripts, but I digress.)

I'm finding that as I work with Ruby, examples are hard to come by.  I
pull out the source to many libraries to read how they work. Some are
informative -- net/http is great -- some are hard to understand, like
webrick -- but I'd really like docs so I don't -have- to read the source
and guess how the library is best used.

Ari