Section 2.13. Ruby Documentation

A Quick Tour of Ruby > Ruby Documentation

2.13. Ruby Documentation

When I say "Section 2.13," I am mostly referring to the documentation that is generated by RDoc (http://rdoc.sourceforge.net/), a program that extracts documentation from Ruby source files, both C and Ruby files.

The documentation is stored in comments in the source files, and encoded so that RDoc can easily find it. For example, equals signs (such as ===) on the left margin set off a heading, and indented text is formatted as code. RDoc can generate output as HTML, XML, ri (Ruby information), or Windows help (chm) files.

To view the RDoc-generated HTML documentation for Ruby, go to http://www.ruby-doc.org/core. If you have Ruby documentation installed on your system, which you likely do if you followed the installation instructions in Chapter 1, you can type something like the following at a shell prompt to get formatted documentation in return. Type:

ri Kernel.print

and you will get output that looks like:

----------------------------------------------------------- Kernel#print
     print(obj, ...)    => nil
------------------------------------------------------------------------
     Prints each object in turn to +$stdout+. If the output field
     separator (+$,+) is not +nil+, its contents will appear between
     each field. If the output record separator (+$\+) is not +nil+, it
     will be appended to the output. If no arguments are given, prints
     +$_+. Objects that aren't strings will be converted by calling
     their +to_s+ method.

        print "cat", [1,2,3], 99, "\n"
        $, = ", "
        $\ = "\n"
        print "cat", [1,2,3], 99

     _produces:_

        cat12399
        cat, 1, 2, 3, 99

In Chapter 10, you'll find a tutorial on creating documentation with RDoc.