From Apply Now,
Your Guide to Ruby.
FREE Newsletter. Sign Up Now!

Summary

Most if not all Ruby distributions include the documentation utilities RDoc and ri. RDoc is used to extract and format the documentation inside Ruby source and output it as either HTML or ri. While you can read the HTML documentation with any web browser, ri is the command-line utility used to read the ri output from RDoc.

NOTE: ri stands for Ruby Interactive, but as that is so close to Interactive Ruby (irb), you will rarely hear it referred to as anything but ri.

Given nicely formatted and browseable HTML, most Ruby developers will probably choose that as their primary source of documentation, but don't dismiss ri entirely as you might find it a quicker way to get the answers you are looking for.

The ri 'can't convert nil' Error

Before going on, it is best to warn you that the a bug lurks in ri that was only fixed as recently as Ruby 1.8.5p1. It shows up as the following error message after installing the documentation for Ruby programs such as Ruby on Rails.

ri_descriptions.rb:99:in `concat': can't convert nil into Array (TypeError)

Notice that "ri_descriptions.rb" is just a Ruby source file and your error lists the full path, though I chose not to show my path for clarity. You can open "ri_descriptions.rb" and update line 99 so that it checks for a nil value. The old code is commented out and a replacement line is shown. The new code uses the conditional modifier "unless" to make sure we are not trying to concatenate a nil "old.comment".

# @comment.concat old.comment
@comment.concat old.comment unless old.comment.nil?

Understanding ri

You might have noticed from the error description above that we are dealing with a Ruby program and ri is just a command-line script used to invoke the RiDriver#process_args method. After processing the specified arguments, ri writes the resulting output to a temporary file and then searches for a pager utility to display that file. If an environment variable named 'PAGER' has been set, it will be used, otherwise ri searches for the 'less' and 'more' utilities in that order. Typically this means 'less' will be the default for *nix based systems and 'more' will be used for Windows.

You can also customize the output of ri using optional arguments. Use the "--help" option to see all of your choices; ri --help. If you find a set of options you want to use as defaults, set an environment variable named "RI" with those options.

Windows users who rely on the default pager 'more' may find the following settings useful. The output is formatted a little nicer and a custom width specified.

set RI= --format ansi --width 100

Users who rely on the 'less' utility can use the same settings but will need to allow for the ansi control characters using the 'less' flag "-R".

export PAGER="less -R"
set RI="--format ansi --width 100"

Most of the time, ri output will easily fit in the terminal (command window), so you might want to skip the use of a pager and specify the "--no-pager" option.

Using ri

Once you get beyond the difficult parts of ri, which is installing the documentation, fixing the nil bug, and dealing with the output options, using ri is remarkably simple. Just specify the Ruby class, module, or method you are interested in, as in the following examples.

ri String

If more than one match is possible, ri will return all of the matches so you can specify the one you want.

ri length
ri String#length

When requesting documentation for method names, there is a difference between ".", "#", and "::". Look at the output for the class String and note that there is a single class method, "new". You can access class and instance methods using ".", otherwise you must use "::" for class methods and "#" for instance methods.

ri String.new
ri String#new # invalid request
ri String::new

One final note, some Ruby names contain characters reserved by your command-line. In these cases you will need to quote the argument to ri.

ri "String.<<"