Cover by Michael Fitzgerald

Safari, the world’s most comprehensive technology and business learning platform.

Find the exact information you need to solve a problem on the fly, or go deeper to master the technologies and skills you need to succeed

Start Free Trial

No credit card required

O'Reilly logo

Creating Documentation with RDoc

RDoc is a tool for generating documentation from Ruby source files, whether written in Ruby or C. It was created by Dave Thomas (http://www.pragmaticprogrammer.com), and comes as part of the Ruby distribution. Documentation is available at http://rdoc.sourceforge.net/doc/index.html.

RDoc parses Ruby source code and collects information from comments, as well as information about methods, constants, and other things. It cross-references what it can before producing default XHTML output in a doc subdirectory. You can embed codes in your comments, too, allowing RDoc to format a page according to your taste.

Tip

If you are a Java refugee, you'll be happy to know that RDoc is similar to Java's Javadoc (http://java.sun.com/j2se/javadoc).

RDoc Basics

I'll present the basics of RDoc here using the file ratios.rb, which contains the class Ratios. The methods in this class calculate a few financial ratios.

I first show the file piece by piece, then later, the whole file. I'll walk you through how to mark up your Ruby source files, and then show you how to process these files to get XHTML or other output. Of course, I won't show you everything you can do with RDoc, just some of the most important things.

The comments before the class definition begins are interpreted as general documentation for the class and are placed before any other documentation. Example 10-10 shows the beginning of ratios.rb.

Example 10-10. Beginning of ratios.rb

# This class provides a few methods ...

Find the exact information you need to solve a problem on the fly, or go deeper to master the technologies and skills you need to succeed

Start Free Trial

No credit card required