A quick RDoc primer

I was working through Exercise 35 of  Zed Shaw’s excellent tutorial Learn Ruby the Hard Way when I hit question three in the Extra Credit section.  There he instructs you to “Write comments for the functions you do not understand. Remember RDoc comments?”  And when I Googled for how to use RDoc, nothing really jumped out. Here’s how difficult it is:

In the directory containing your Ruby file, type:

"rdoc <name_of_ruby_file"

That’s it.

That command kicks off a small set of actions, including a scan of your code. Note that it found only a single class, and lists many items as “undocumented.”

The command also creates a “doc” directory containing HTLM, CSS, and Javascript files for presenting documentation of your code.

Opening the index.html file you find in that directory will reveal your documented code:

RDoc has cleanly listed out the objects it found in your file, as well as the methods it discovered. Clicking on any of the method names drills down into more detail, including showing the method code itself:

All this was generated with one simple command.  To truly unlock the power of RDoc, you need to add a few more detailed comments to your code. Such comments allow RDoc to provide much greater detail on the code itself, and remove the “undocumented” response when you build your RDoc documentation.

It will also help anyone in the future who wants to implement your code-which is the whole point of RDoc.