From: "jbritt@..." <jbritt@...>
Date: 2003-07-29T16:01:30+09:00
Subject: Re: Documentation for standard library -- what format?

William Webber wrote:
> Hi all!
> 
> I'm a bit confused as to what is meant to be the standard
> format for documentation in the standard library.  For
> instance, in the Net package, Net::ftp has relatively newly
> contributed documentation in RDoc, whereas Net::http,
> Net::imap, Net::pop, Net::smtp and Net::telnet have very
> full documentation in RD, and Net::protocol is essentially
> undocumented.

RD was the first, or one of the first, formats used to document code.
Rdoc came along and is, I beleive, the prefered format.  Of course, 
there is still a good deal of code around with RD.
> 
> I ask because I got bored at work the other day and started
> documenting Net::ftp in RD on RDP 
> (http://www.rubyist.net/~rubikitch/RDP-en.cgi?cmd=src;name=net),
> before checking to see what the current (1.8preview5)
> documentation state was, and now I'm confused as to whether
> I should continue with this or not.

Well, first let me say "Thank you!"  Documentation is often a scorned, 
thankless task.  Personally I prefer RDoc format, and I believe that is 
what most people now choose.

> 
> Also, is there going to be an "authoritative" source for
> standard library documentation (something like the JDK API's
> Javadoc, or Python's library documentation), and if so,
> where is it going to reside?  

There are efforts underway to add RDoc comments to the Ruby source tree, 
such that code and documentation are maintained at the same time.

API documments would be created by running RDoc on the source; there 
should be no need for a primary repository for the document other than 
the source code CVS.  (And these comments should be going into ri, the 
Ruby command-line help system, so every installation of Ruby should have 
complete docs for at least the built-in classes, and possibly the 
standard library.)


> It took me a long time as a
> nuby to figure out where documentation was, and I was
> equally confused yesterday when I did a search around the
> various Ruby documentation sites and projects (RDP,
> www.ruby-doc.org, www.rubydoc.org (!), the Pickaxe book, the
> embedded documentation, the old 1.4.6 reference manual
> (which is the bundled documentation that comes with Ruby on
> RedHat 8.0 and 9.0), various wikis, etc.).  The ruby
> community seems to spawn documentation projects like the
> scheme community spawns scheme interpreters. :-)  Again, I
> ask because I'd like to contribute (if contributions are
> sought), but I'm not sure what to contribute to...

Of course, various sites will have mirrors of the generated docs.
I manage www.ruby-doc.org and try to keep it up-to-date by either 
hosting documentation directly or by linking to whatever is known to exist.

I suppose there would be advantages to having a single, cannonical URL 
for documentation, but I'm happy to see anybody add documentation, even 
if it means Yet Another Site.  By and large, so long as these sites are 
linking to each other then really shouldn't be an issue.

If you (or anybody) have something and would like a place to host it, 
please send it to me (unless it's a gigantic AVI file or something; I 
need to figure out bandwidth costs and caps for ruby-doc.org before 
hosting anything large.)


James Britt
> 
> William Webber
> 
>