rdoc: Ruby Standard Library Documentation

Ruby 1.9.1

This package contains RDoc and RDoc::Markup. RDoc is an application that produces documentation
for one or more Ruby source files. We work similarly to JavaDoc, parsing
the source, and extracting the definition for classes, modules, and methods
(along with includes and requires). We associate with these optional
documentation contained in the immediately preceding comment block, and
then render the result using a pluggable output formatter. RDoc::Markup is a library that converts
plain text into various output formats. The markup library is used to
interpret the comment blocks that RDoc uses to
document methods, classes, and so on.

Once installed, you can create documentation using the ‘rdoc’ command (the
command is ‘rdoc.bat’ under Windows)

% rdoc [options] [names...]

Type “rdoc –help” for an up-to-date option summary.

A typical use might be to generate documentation for a package of Ruby
source (such as rdoc itself).

% rdoc

This command generates documentation for all the Ruby and C source files in
and below the current directory. These will be stored in a documentation
tree starting in the subdirectory ‘doc’.

You can make this slightly more useful for your readers by having the index
page contain the documentation for the primary file. In our case, we could
type

% rdoc --main rdoc.rb

You’ll find information on the various formatting tricks you can use in
comment blocks in the documentation this generates.

RDoc uses file extensions to determine how to
process each file. File names ending .rb and
.rbw are assumed to be Ruby source. Files ending
.c are parsed as C files. All other files are assumed to
contain just Markup-style markup (with or without leading '#' comment
markers). If directory names are passed to RDoc,
they are scanned recursively for C and Ruby source files only.

For information on how to make lists, hyperlinks, & etc. with RDoc, see RDoc::Markup.

Comment blocks can be written fairly naturally, either using ‘#’ on
successive lines of the comment, or by including the comment in an
=begin/=end block. If you use the latter form, the =begin line must be
flagged with an RDoc tag:

Documentation to be processed by RDoc.
...

RDoc stops processing comments if it finds a
comment line containing '#--'. This can be used to separate
external from internal comments, or to stop a comment being associated with
a method, class, or module. Commenting can be turned back on with a line
that starts '+#+++'.

### Extract the age and calculate the date-of-birth.#--# FIXME: fails if the birthday falls on February 29th#++# The DOB is returned as a Time object.defget_dob(person)
# ...end

Names of classes, source files, and any method names containing an
underscore or preceded by a hash character are automatically hyperlinked
from comment text to their description.

Method parameter lists are extracted and displayed with the method
description. If a method calls yield, then the parameters
passed to yield will also be displayed:

def fred
...
yield line, address

This will get documented as:

fred() { |line, address| ... }

You can override this using a comment containing ‘:yields: …’ immediately
after the method definition

def fred # :yields: index, position
# ...
yield line, address

which will get documented as

fred() { |index, position| ... }

:yields: is an example of a documentation directive. These
appear immediately after the start of the document element they are
modifying.

Don’t include this element in the documentation. For classes and modules,
the methods, aliases, constants, and attributes directly within the
affected class or module will also be omitted. By default, though, modules
and classes within that class of module will be documented. This
is turned off by adding the all modifier.

Force a method or attribute to be documented even if it wouldn’t otherwise
be. Useful if, for example, you want to include documentation of a
particular private method.

:notnew:

Only applicable to the initialize instance method. Normally
RDoc assumes that the documentation and
parameters for initialize are actually for the ::new method, and so fakes
out a ::new for the class. The :notnew: modifier stops this. Remember
that initialize is protected, so you won’t see the documentation unless you
use the -a command line option.

Comment blocks can contain other directives:

+:section: title+

Starts a new section in the output. The title following
:section: is used as the section heading, and the remainder of
the comment containing the section is used as introductory text.
Subsequent methods, aliases, attributes, and classes will be documented in
this section. A :section: comment block may have one or more lines before
the :section: directive. These will be removed, and any identical lines at
the end of the block are also removed. This allows you to add visual cues
such as:

# ----------------------------------------# :section: My Section# This is the section that I wrote.# See it glisten in the noon-day sun.# ----------------------------------------

:call-seq:

Lines up to the next blank line in the comment are treated as the method’s
calling sequence, overriding the default parsing of method parameters and
yield arguments.

:include:filename

Include the contents of the named file at this point. The file will be
searched for in the directories listed by the --include
option, or in the current directory by default. The contents of the file
will be shifted to have the same indentation as the ‘:’ at the start of the
:include: directive.

:title:text

Sets the title for the document. Equivalent to the –title command line
parameter. (The command line parameter overrides any :title: directive in
the source).

:enddoc:

Document nothing further at the current level.

:main:name

Equivalent to the –main command line parameter.

:stopdoc: / :startdoc:

Stop and start adding new documentation elements to the current container.
For example, if a class has a number of constants that you don’t want to
document, put a :stopdoc: before the first, and a
:startdoc: after the last. If you don’t specify a
:startdoc: by the end of the container, disables documentation
for the entire class or module.