RDoc is the name given to a Ruby source code documentation format and tool. The RDoc tool, which comes standard with Ruby, can process Ruby code files and Ruby’s C-code class library in order to extract documentation and format it so that it can be displayed in, for example, a web browser. You can explicitly add RDoc documentation to your own code in the form of source code comments. The RDoc tool can also extract elements of the source code to provide the names of classes, modules, and methods, along with the names of any arguments required by methods.

It is easy to document your own code in a way that is accessible to the RDoc processor. Either you write a block of ordinary single-line comments before the code being documented (such as a class or method) or you write an embedded multiline comment delimited by =begin rdoc and =end. Note that rdoc must follow =begin; otherwise, the RDoc processor will ignore the comment block:

=begin rdoc
This is an RDoc comment
=end

This example, using single-line comments, is taken from the RDoc documentation:

# Determine the letters in a word or phrase
#
# * all letters are converted to lowercase
# * anything not a letter is stripped out
# * the letters are converted into an array
# * the array is sorted
# * the letters are joined back into a string
def letters_of(text)
    text.downcase.delete('^a-z').split('').sort.join
end

Here the * characters instruct RDoc to format items as a bulleted list, producing output similar to the following:

letters_of(text)
Determine the letters in a word or phrase
    • all letters are converted to lowercase
    • anything not a letter is stripped out
    • the letters are converted into an array
    • the array is sorted
    • the letters are joined back into a string

When you are ready to generate the documentation, you just need to run the RDoc processor from the command prompt. To generate documentation for a single file, enter rdoc followed by the name of the file:

rdoc rdoc1.rb

To generate documentation for multiple files, enter the filenames separated by spaces after the rdoc command:

rdoc rdoc1.rb rdoc2.rb rdoc3.rb

The RDoc tool will create a nicely formatted HTML file (index.html) with three panes at the top and a fourth, larger pane at the bottom. The three top panes display the names of the files, classes, and methods, while the bottom pane displays the documentation.

The HTML contains hyperlinks so that you can click class and method names to navigate to the associated documentation. The documentation is placed into its own subdirectory, doc, along with a number of required HTML files and a style sheet to apply formatting.

You can add extra formatting to your RDoc comments by placing formatting characters around single words or by placing tags around multiple words. Use * and * for bold, _ and _ for italic, and + and + for a monospaced, “typewriter” font. The equivalent tags for longer pieces of text are <b> and </b> for bold, <em> and </em> for italic, and <tt> and </tt> for typewriter.

If you want to exclude comments, or parts of a comment, from the RDoc documentation, you can place it between #— and #++ comment markers, like this:

#--
# This comment won't appear
# in the documentation
#++
# But this one will

Special instructions are also available, enclosed between pairs of colons. For instance, if you want to add a title to be displayed in the browser bar, use :title: like this:

#:title: My Fabulous RDoc Document

Many more options are available with RDoc to enable you to format documentation in a variety of ways and output in alternative formats to HTML. If you really want to master RDoc, be sure to read the complete documentation, available online at http://rdoc.sourceforge.net/doc/index.html.