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
subdirectory. You can embed codes in your comments, too, allowing RDoc to format a page
according to your taste.
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).
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 ...