5 Reasons You Should Use ri To Read Ruby Documentation

Published on September 13, 2012 by Jesse Storimer

ri is a tool that ships with Ruby. It's a companion to rdoc, allowing you to 'display information about Ruby classes, modules, and methods' from your console. Despite its usefulness it's often overlooked in favour of searching Google.

$ ri File
$ ri Fil
$ ri File.directory?
$ ri Socket#accept
$ ri ActiveRecord::Base.touch

Over the last few months I've started using ri more and more. Once it became part of my workflow I really couldn't believe that I wasn't using it before. And I can't believe you're not using it now!

Here's why:

1. ri Actually Understands Ruby

Something interesting happens when you look for the ActiveRecord::Base#save docs:

$ ri ActiveRecord::Base#save
(from gem activerecord-3.2.8)
Implementation from ActiveRecord::Persistence


(from gem activerecord-3.2.8)
Implementation from ActiveRecord::Validations


(I trimmed the output for brevity.)

Notice that it returned documentation from two different modules, neither of which is technically ActiveRecord::Base. That's because ri understands that those modules are included into ActiveRecord::Base so their docs are relevant.

Searching Google for the same thing will not return results that precise.

2. It's Faster Than The Web

Prior to using ri I would just search Google. This works but adds overhead to what, otherwise, could be a simple lookup on the local filesystem. Going to the web will require at least two network requests (one for the Google Search, one for displaying the documentation site).

Not to mention that I don't have to leave the comfort of my terminal to open a web browser.

3. It's Consistent

There are many different web sites that display Ruby docs. They all display documentation slightly differently, show examples slightly differently, have different sidebars, etc.

When using ri you get a minimal, consistent interface for reading docs.

4. Interactive Mode

Try starting ri with the -i option. This drops you into an interactive documentation repl. Start typing the classes and methods you're looking for and use <tab> for autocompletion. After reading one set of docs you're returned to the console for more searching.

5. You Already Have It

ri ships with your Ruby install, so you don't need to install anything. The rdoc for core Ruby methods is installed for you when you install Ruby.

So you can start using ri right away!

Getting ri For All of Your Gems

There's a good chance that, up until now, you've had the following in your ~/.gemrc:

gem: --no-ri --no-rdoc

If you want to use ri then delete that first option. You can leave --no-rdoc there, that specifically generates HTML docs. Now any new gems you install will have their ri docs installed as well.

If you want to generate the missing ri docs for all your installed gems you can:

$ gem rdoc --all --ri --no-rdoc


I'm happier using ri for my Ruby documentation needs. Give it a try!

If you know any other tricks leave them in the comments!

Like what you read?

Join 2,000+ Ruby programmers improving their skills with exclusive content about digging deeper with sockets, processes, threads, and more - delivered to your inbox weekly.

I'll never send spam and you can unsubscribe any time.

comments powered by Disqus