From: Holden Glova <dsafari@...>
Date: 2002-07-23T19:41:08+09:00
Subject: Re: rdtool and rdoc

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Tue, 23 Jul 2002 03:28, 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

While I don't comment my code too extensively, I do find RDoc is a nice 
unobtrusive way to present code level documentation. A professional tool like 
this is also essential for me to persuade work that Ruby is ready for prime 
time. My collegues drolled over RDoc as I showed them the beauty of it 
compared to javadoc.

I would like to see the Ruby API available in RDoc format, and being able to 
add to ri would be fantastic!

- -- 
Signed,
Holden Glova
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.7 (GNU/Linux)

iD8DBQE9PTJ70X8w8X71zPcRAtGkAJoCAB0FZCDNQV7A48njXyB9JnkJfACdF6Mz
3rSqSBuvBpXR1QEheH7Kcfo=
=cTMB
-----END PGP SIGNATURE-----