One longstanding weakness with the Ruby community is subpar documentation. I think many Rubyists tend to look down on actual API documentation, preferring instead to just read source code directly. I've been guilty of this too and I think some of this is due simply to unfamiliarity with RDoc. Let's change that now.

Creating RDoc

I've never found an easily accessible RDoc markup reference. The only one I know of is unlinkable, buried at the bottom of the RDoc readme instead of front and center as it should be. So I extracted the RDoc markup reference for your reading pleasure. Jan Varwig created a great RDoc cheatsheet PDF for local or offline access.

Next time you're working on a gem, take 10 minutes to read the reference and document the main class for the gem. It'll make you a better Rubyist, I guarantee it.

Generating RDoc

Ok, so you've learned RDoc markup and your code is documented like a champ. What do you do now? You've got several choices:

Once generated, you can view the generated output at doc/index.html.

Viewing RDoc

Rubygems has built-in support for generating and viewing the RDoc for installed gems. rdoc is generated when the gem is installed (using gem install --no-rdoc [name] skips the local rdoc generation). You can then use gem server to view your local gem rdoc at http://localhost:8808.

Check out YARD

YARD is an interesting project by Loren Segal to create a next generation Ruby documentation system. Getting started with YARD is well documented; try it out if you want an alternative to RDoc. YARD's syntax is a superset of RDoc's so backwards compatibility should not be an issue. The generated documentation looks pretty awesome (note the support for Markdown-formatted README files, which RDoc does not have).

The YARD team also created RubyDoc.info, which hosts documentation for popular gems and is a great resource for finding linkable documentation.

I hope this helps de-mystify rdoc for people. Any other rdoc tips, please leave a comment. Happy documenting!

comments powered by Disqus