Section 17.2. Installation and Packaging

17.1. Using RDoc

RDoc isn't the only doc tool around for Ruby; RDTOOL is older. But in many ways, RDoc is superior; it's also more commonly used, at least in the United States.

One great thing about RDoc is that it tries to produce useful output even if there are no comments in the source. It does this by parsing the code and organizing information on all the classes, module, constants, methods, and so on.

Therefore you can get reasonably useful HTML out of a program source that doesn't even have any real internal documentation. If you haven't tried this before, I suggest you try it.

But it gets better. RDoc also tries to associate the comments it finds with specific parts of the program. The general rule is: A block comment preceding a definition (such as a class or method) will be taken as the description of that definition.

If you simply invoke RDoc on a Ruby source, it will create a doc directory with all the files under it. (The default template looks good, but there are others.) Browse to index.html and take a look.

Listing 17.1 shows a simple (nearly empty) source file. All the methods are empty, and none of it really does anything. But RDoc will still take it and produce a pretty doc page (see Figure 17.1).

Listing 17.1. A Simple Source File

require 'foo' # The outer class, MyClass class MyClass   CONST = 237   # The inner MyClass::Alpha class...   class Alpha     # The MyClass::Alpha::Beta class...     class Beta       # Beta's mymeth1 method       def mymeth1       end     end     # Alpha's mymeth2 method     def mymeth2     end   end   # Initialize the object   def initialize(a,b,c)   end   # Create an object with default values   def self.create   end   # An instance method   def do_something   end end

Figure 17.1. RDoc output from source in Listing 17.1.

We'll discuss two other useful features in this section. Every method name is linked to a pop-up that displays the source code of that method. This is an absolutely invaluable tool in learning a library; the API documentation is linked directly back to the code itself.

Also be aware that when RDoc recognizes a URL, it places a hyperlink in the output. The text of the link defaults to be the same as the URL, but you can change this. If you put descriptive text in braces followed by a URL in brackets ({descriptive text}[myurl]), your descriptive text will be used in the link. If the text is a single word, the braces may be omitted.

17.1.1. Simple Markup

If you want to "decorate" your output more, you don't have to edit the HTML files. In fact, that's a bad idea since it's so easy to regenerate the output (and overwrite your changes).

RDoc has a simple markup facility of its own so that you can embed your own formatting information into your source code. The markup rules are chosen so that the text looks "natural" in an editor, but it can be translated into HTML in a straightforward way.

Listing 17.2 shows a few examples of markup capability; for more examples, consult Programming Ruby or any other source of RDoc documentation. The output (bottom frame only) from Listing 17.2 is shown in Figure 17.2.

Listing 17.2. Examples of RDoc Markup

# This block comment will be detected and # included in the rdoc output. # =begin rdoc So will this one. Note the presence of the "rdoc" tag on the begin-line. This is to distinguish the block comment as belonging to rdoc as opposed to being read by some other tool. =end =begin rdoc Here are some formatting tricks. Boldface, italics, and "code" (without spaces): This is *bold*, this is _italic_, and this is +code+. With spaces: This is a bold phrase. Have you read Intruder in the Dust? Don't forget to require thread at the top. = First level heading == Second level heading === Third level heading Here's a horizontal rule: --- Here's a list: - item one - item two - item three =end =begin This block comment is untagged and will not show up in rdoc output. Also, I'm not putting blank lines between the comments, as this will terminate the comments until some real program source is seen. If this comment had been before the previous one, processing would have stopped here until program text appeared. =end

Figure 17.2. RDoc output from markup examples in Listing 17.2.

Listing 17.2 outlines some of the rules RDoc uses to parse comments. Not all of these are necessarily intuitive. There is a strong tendency for blank lines to terminate a section of comments, even if the blank line is immediately followed by another block comment.

Note that inside a block comment starting with #, we can "turn off" the copying of text into the output with a #-- line (and turn it back on again the same way). Not all comments are intended to go into the user docs, after all.

Note also that if =begin and =end are used, they must have an rdoc tag after the =begin, or RDoc will ignore the block. This is to avoid conflict with older tools that make heavy use of such blocks.

17.1.2. More Advanced Formatting

RDoc gives you relatively fine control over what parts of your source are documented and how they are treated. Special tags in the comments (documentation modifiers) accomplish this.

One of the most important of these is :nodoc: (to turn off documentation for something you don't want to appear in output). Typically this is used on the same line when a class or method is introduced.

class Alpha     # :nodoc:   class Beta     # ...   end   # ... end

In the preceding example, Alpha would not be documented. However, :nodoc: is not recursive; Beta would still be documented. To make it recursive, use :nodoc: all instead. In the following example, both Gamma and Delta will be ignored:

class Alpha     # :nodoc: all   class Beta     # ...   end   # ... end

There's also a :doc: modifier, which is the opposite. It forces documentation for things that ordinarily would not appear in output.

The :notnew: modifier is special; it prevents the documenting of a new method (based on an existing initialize method).

If you want to give meaningful names to your yield parameters, you can use the yields keyword. For example, your code may use boring parameter names such as x and i; you can change these in the documentation.

def iterate    # :yields: element, index   # ...   yield x, i end

Some tags are used only inside block comments. Here are most of them:

• :include: Include the contents of the specified file in the documentation. Indentation will be adjusted for consistency.

• :title: Set the title of the document.

• :main: Set the initial page displayed in the output.

For more information, consult Programming Ruby or any reference you can find online.