From: Charles Hixson <charleshixsn@...>
Date: 2002-07-24T07:41:42+09:00
Subject: Re: rdtool and rdoc

Dave Thomas wrote:

>Minero Aoki <aamine@mx.edit.ne.jp> writes:
>
>  
>
>>  In this thread, Nobuyoshi Nakada has noted that he had imported
>>  OptionParser (optparse.rb) to the CVS repository.  This is the
>>  preparation to bundle RDtool into the standard package.
>>    
>>
>
>At this risk of sounding biased... :)
>
>I'm wondering if any consideration was given to including RDoc in the
>base distribution?
>
>I think RDTool is a wonderful utility for creating general purpose
>documentation: if I were writing a manual I'd seriously consider using
>it. However, I personally find it quite cumbersome when using it to
>document source files: the documentation breaks up the source, and the
>documentation writer is forced to repeat much of the information that's
>in the source itself. That's why I wrote RDoc. Because it understands
>the syntax of the languages it's documenting (Ruby, C extensions, and
>Fortran currently) , it can produce meaningful output even if the
>input file contains no documentation whatsoever. If also has output
>options that are useful when working with source code (such as the
>pseudo file/module/method browser bar for quick navigation, automatic
>hyperlinks, and pop-up source code for method (just click on the
>method name).
>
>I've put up a small compare-and-contrast page at
>
>    http://rdoc.sourceforge.net/rd/
>
>
>So... A suggestion. I'd like to propose RDoc as the tool used to
>document Ruby libraries and the Ruby interpreter itself. We could use
>the text from the PickAxe for the interpreter documentation and for
>many of the libraries, and the others could be added as we go along.
>
>For this to be useful, we'd need to bundle RDoc with Ruby.
>
>
>Cheers
>
>
>Dave
>
>  
>
rdoc looks nice, and it works well for small pieces of code.  But when 
you use it for a large piece of code you run into problems, because the 
methods listed are not separated by the class they are a member of.  (I 
tried to use it that way a couple of weeks ago when the PickAxe book was 
offline.)  I don't know how well RDTool would have worked for that, it 
seems more aimed at printouts, but doesn't itself produce any search 
capability at all.

As far as the source code goes (from you examples), I find the rdoc code 
to be much more readable.  Also, the rdoc comments look much more likely 
to get done, and definitely more likely to be kept current.

-- 
-- Charles Hixson
Gnu software that is free,
The best is yet to be.