Recipe 2.10. Generating RDoc for Your Rails Application

Problem

You want to document the source code of your Rails application for the benefit of other developers, maintainers, and end users. Specifically, you want to embed comments in your source code and run a program to extract those comments into a presentable format.

Solution

Since a Rails application is composed of a number of Ruby source files, you can use Ruby's RDoc facility to create HTML documentation from specially formatted comments that you embed in your code.

You can place comments at the top of a class file and before each of the public instance methods defined in the class file. You then process the directory containing these class definitions with the rdoc command, which processes all Ruby source files and generates presentable HTML documentation.

For example, you may have a cookbook application that defines a ChaptersController. You can mark up the ChaptersController file with comments:

                # This controller contains the business logic related to cookbook  # chapters. For more details, see the documentation for each public # instance method. class ChaptersController < ApplicationController   # This method creates a new Chapter object based on the contents   # of <tt>params[:chapter]</tt>.    # * If the +save+ method call on this object is successful, a    #   flash notice is created and the +list+ action is called.   # * If +save+ fails, the +new+ action is called instead.   def create     @chapter = Chapter.new(params[:chapter])     if @chapter.save       flash[:notice] = 'Chapter was successfully created.'       redirect_to :action => 'list'     else           render :action => 'new'     end   end ...

The comments consist of one or more consecutive lines preceded with a hash mark (#) to form blocks of descriptive text. The top comment block in the file should describe the function of the overall class, and may contain usage examples or show how the class is used within the context of the rest of the application.

Once you've added comments to the classes, use the Rake doc:app to generate RDoc HTML for the application. From the root of the cookbook application, running the following command creates a directory named doc/app that contains a number of HTML files:

$ rake doc:app             

$ ls -F doc/app/ classes/     files/               fr_file_index.html    index.html created.rid  fr_class_index.html  fr_method_index.html  rdoc-style.css

You can view the results of running RDoc on your application by pointing a browser to doc/app/index.html.

Discussion

Figure 2-4 shows the RDoc HTML generated from the solution's example application. The ChaptersController has been selected from the Classes navigation frame and is shown in the main window in the frame set.

Figure 2-4. A Rails application's generated RDoc HTML

The documentation rendered for the create method demonstrates a few of the many wiki-style formatting options you can use within RDoc comments. One feature of the documentation is that HTML pages are interlinked. For example, the word "Chapter" in the description of the create method is turned into a hyperlink to the documentation of the Chapter model class definition. Here are some other common formatting options:

# = Heading One #  # == Heading Two #  # === Heading Three

The following produces heading of various sizes:

# * One # * Two # * Three

This code creates a bulleted list of items:

# 1. One # 2. Two # 3. Three

The following creates an ordered list of items:

# Fixed with example code: #   class WeblogController < ActionController::Base #     def index #       @posts = Post.find_all #       breakpoint "Breaking out from the list" #     end #   end

To specify that example code should rendered with a fixed-width font, indent it two spaces past the # character.

You can also create a list of terms and definitions:

# [term] This is the definition of a term.

This comment line creates a definition-style pairing in which "term" is being defined by the text that follows it.

Within paragraphs, you can italicize text with underscores (e.g., _emphasized_) or create bold text by surrounding words with "splats" (e.g., *bold*). You can specify inline text be rendered with a fixed with font by surrounding words with "+" (e.g., +command+).

By default, RDoc ignores private methods. You can explicitly tell RDoc to reveal the documentation for a private method by adding the :doc: modifier to the same line as the function definition. For example:

private   def a_private_method # :doc:   end

Similarly, you can hide code from the documentation with the :nodoc: modifier.

See Also

• RDoc project, http://rdoc.sourceforge.net