# Ruby Programming/RubyDoc

← Unit testing | RubyGems →
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
Just to get going, run rdoc on this file
A quick look around reveals rdoc has created a new directory called doc/. It contains quite a few files (given such a simple class!)
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):
* The lists can be labeled. Each label must be inside square brackets or followed by two colons:
* 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:
You can avoid having a link created like
(won't be linked) and
for camelcase that shouldn't be linked to known classnames.

### linking to a url

Here's an example:

## 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:
Which when run:
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:
This time with section headers. Running the script gives
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!