Documentation for standard library -- what format?

[William Webber]

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:op, Net::smtp and Net::telnet have very
full documentation in RD, and Net:rotocol is essentially
undocumented.

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.

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

William Webber

 

[jbritt]

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:op, Net::smtp and Net::telnet have very
full documentation in RD, and Net:rotocol 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

 

[Dan Debertin]

RD was the first, or one of the first, formats used to document code.
Rdoc came along and is, I beleive, the prefered format.

With due respect to the authors of RDoc, I have to confess that I'm a
bit surprised that it still doesn't have a manpage/perldoc-ish
interface. That is why I stopped using it; I refuse to swap between an
editor and a web browser in order to access documentation (and often
the machine I'm using doesn't have a browser).

Is anyone working on this? Did I miss something?


Dan

 

[james_b]

Eventually ri and rdoc will be integrated, and you'll have your wish
(and more). However, first I need to invent a machine to make time go
slowly while I code.

In the interim there is Rimport, which aids in geting RDoc output into ri.

http://www.ruby-lang.org/en/raa-list.rhtml?id=413


James