Documentation for standard library -- what format?

Discussion in 'Ruby' started by William Webber, Jul 29, 2003.

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

    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
     
    William Webber, Jul 29, 2003
    #1
    1. Advertising

  2. William Webber

    Guest

    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
    >
    >
     
    , Jul 29, 2003
    #2
    1. Advertising

  3. William Webber

    Dan Debertin Guest

    "" <> writes:


    > 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
    --
    /^Dan Debertin$/ |
    |
    www.nodewarrior.org |
     
    Dan Debertin, Jul 29, 2003
    #3
  4. William Webber

    james_b Guest

    Dave Thomas wrote:
    >
    > 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

    >
    > Cheers
    >
    >
    > Dave
    >
    >
    >
     
    james_b, Jul 30, 2003
    #4
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Teddy
    Replies:
    3
    Views:
    348
    osmium
    Jul 23, 2003
  2. Water Cooler v2

    Downloadable C Standard library documentation

    Water Cooler v2, Aug 14, 2007, in forum: C Programming
    Replies:
    1
    Views:
    382
    santosh
    Aug 14, 2007
  3. Gavin Sinclair
    Replies:
    7
    Views:
    118
    Raphael Bauduin
    Oct 31, 2003
  4. Gavin Sinclair
    Replies:
    0
    Views:
    89
    Gavin Sinclair
    Dec 11, 2003
  5. Andreas Schwarz
    Replies:
    6
    Views:
    264
    Randy W. Sims
    Jan 1, 2004
Loading...

Share This Page