Ruby Best Practices

API Documentation via RDoc

RDoc provides an easy and powerful way to document your Ruby APIs. By simply writing comments in your source code with some lightweight markup here and there, you can automatically generate comprehensive documentation. Of course, a documentation tool isn’t going to be all that useful without some solid guidelines for how functions should actually be documented. We’ll cover both RDoc and Ruby documentation best practices here, as they complement each other nicely.

Basic Documentation Techniques and Guidelines

Usually, you’ll want to start off the documentation for any function with a short description of what it does. You can then follow up with a description of the accepted arguments and any defaults used. Finally, if it makes sense to do so, an example or two helps make things easier to follow. Figure 8-2 shows how we do this for the Prawn::Document constructor method.

Figure 8-2. Sample API documentation of a method from Prawn

Although the end result is nicely formatted, it doesn’t take much extra work in the source comments to get this sort of output. Here’s what the actual code comments that match Figure 8-2 look like:

class Prawn::Document # Creates a new PDF Document. The following options are available: # # <tt>:page_size</tt>:: One of the Document::PageGeometry::SIZES [LETTER] # <tt>:page_layout</tt>:: Either <tt>:portrait</tt> or <tt>:landscape</tt> ...