Ruby Programming/RubyDoc

The standard Ruby library provides a tool for generating documentation from self documenting code called RubyDoc or RDoc for short. Though it's part of the standard library, RDoc isn't a file you require to use. Instead it consists of a command-line program called rdoc and a library for parsing specially-formatted comments out of Ruby and C code.

A Simple Example

Here are the contents of the file simpleNumber.rb which contains a class SimpleNumber

# This file is called simpleNumber.rb
# It contains the class SimpleNumber

class SimpleNumber

  def initialize( num )
    raise if !num.is_a?(Numeric)
    @x = num
  end

  def add( y )
    @x + y
  end

  def multiply( y )
    @x * y
  end

end

Just to get going, run rdoc on this file

>> rdoc simpleNumber.rb

                    simpleNumber.rb: c...
Generating HTML...

Files:   1
Classes: 1
Modules: 0
Methods: 3
Elapsed: 0.426s

A quick look around reveals rdoc has created a new directory called doc/. It contains quite a few files (given such a simple class!)

>> ls doc/
classes      files                fr_file_index.html    index.html
created.rid  fr_class_index.html  fr_method_index.html  rdoc-style.css

Open the file doc/index.html in a web browser and find

What has RDoc done? First, it has scanned the given file (shown in the upper left pane). The middle pane lists all of the classes in simpleNumber.rb, and the right panel gives all of the methods in SimpleNumber. In this case the lower panel is showing the summary information for the file simpleNumber.rb which has been extracted from the top-level comment in the file. Once we select either a class or a function it will show more particular information.

Handling Multiple Files

Any directories included on the command line will be searched for Ruby files (with an .rb or .rbw extension) and C files (with a .c extension). rdoc will search recursively, which makes it convenient for documenting large trees of code. If no source files are specified, RubyDoc will start searching with the current directory. The output is always generated in a directory doc/ under the current location.

Any files which aren't recognized as Ruby or C are not parsed by default, but can be included as command-line arguments to rdoc. In this case they are treated as SimpleMarkup (see below) -- generally speaking they will just be browsable as plain text files in the HTML documention.

Formatting for RDoc

RDoc uses a formatting system called SimpleMarkup for its markup purposes. SimpleMarkup is a simplified text-based markup system, much like many wiki markup languages. Here's a brief overview:

• Consecutive lines aligned on the left margin (either column 0 in a text file, or after the comment character and whitespace in a source file) are considered a paragraph. An empty line starts a new paragraph.
• If a line starts with "*", "-" or "<a digit>" the following information is a list item, either unnumbered or numbered. All subsequent lines should be indented to match the text on the first line of the list item. Here's an example (from the RDoc documentation):

* this is a list with three paragraphs in
   the first item. This is the first paragraph.

   And this is the second paragraph.

   1. This is an indented, numbered list.
   2. This is the second item in that list

   This is the third conventional paragraph in the
   first list item.

* This is the second item in the original list

• The lists can be labeled. Each label must be inside square brackets or followed by two colons:

    [cat]  a small furry mammal
           that seems to sleep a lot

    [ant]  a little insect that is known
           to enjoy picnics

    cat::  a small furry mammal
           that seems to sleep a lot

    ant::  a little insect that is known
           to enjoy picnics

• Any line which starts to the right of the current left margin is considered verbatim text (like program code, for example)
• Any line starting with one or more equals signs is a heading. One equals sign is a top-level header, two equals signs is a second-level heading, etc.
• Three or more dashes on a line give a horizontal line.
• Basic text markup:
  • Tags can be used, including asterisks for *bold text*, underscores for _emphasis_ text, and plus signs for +code+ text.
  • Alternately, HTML tags can be used.

linking to other methods

To link to other methods format them like ri, ex:

# same as the #read method of the 

You can avoid having a link created like

\#method_name

(won't be linked) and

\Win32

for camelcase that shouldn't be linked to known classnames.

linking to a url

Here's an example:

# For detail, see the msdn[http://msdn.microsoft.com].

Including Diagrams

If the program dot from the Graphviz is available, RDoc will generate class hierarchy diagrams as part of the HTML documentation. This behavior can be enabled with the command line option --diagram or -d.

Using RDoc to Generate Usage Output

Warning : This feature is only available in Ruby 1.8.X; Support for this feature has been dropped as of Rdoc for Ruby 1.9.X.

RDoc can be used to generate a command-line usage string (paragraph) from a file's comments. This is done with the class method RDoc::usage. Here's an example:

# TestRDocUsage: A useless file
#
#  Usage:  ruby testRDocUsage.rb  [options]
#

require 'rdoc/usage'

RDoc::usage

Which when run:

>> ruby testRdocUsage.rb 
TestRDocUsage: A useless file

 Usage:  ruby testRDocUsage.rb  [options]

Not particularly interesting. RDoc::usage can take two kinds of command line options. If the first argument is an integer, this value is used as the exit code for the application (yes, RDoc::usage terminates the application). Any further (string) arguments call out sections of the introductory comment which should be used. Here's a slightly more complicated version of the above example:

#= Overview
# TestRDocUsage: A useless file
#
#= Usage
#
#  Usage:  ruby testRDocUsage.rb  [options]
#

require 'rdoc/usage'

RDoc::usage('Usage')

This time with section headers. Running the script gives

>> ruby testRdocUsage.rb 

USAGE
=====
  Usage:  ruby testRDocUsage.rb  [options]

Where only the 'Usage' section (called out as an argument to RDoc::usage) is included.

Other Interesting Command-Line Options

Here are a selection of other interesting rdoc command-line options which haven't been covered above:

-a, --all

Parse all class methods, not just public methods.

-x, --exclude pattern

Exclude files/directories matching pattern from search. Files included explicitly on the command line are never excluded.

External Links

• RDoc documentation (generated using RDoc!) at Ruby-Doc

Questions

• How do you include an external image file when publishing RDoc inside a Gem? RDoc keeps converting the image into html!