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.
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
(won't be linked) and
for camelcase that shouldn't be linked to known classnames.
Here's an example:
# For detail, see the msdn[http://msdn.microsoft.com].
Using RDoc with RI
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.
- How do you include an external image file when publishing RDoc inside a Gem? RDoc keeps converting the image into html!