RDoc Markup

Comment blocks can be written fairly naturally.

Paragraphs are lines that share the left margin. Text indented past this margin are formatted verbatim.

Lists are typed as indented paragraphs with:
- a '*' or '-' (for bullet lists)
- a digit followed by a period for numbered lists
For example, the input that produced the above paragraph looked like
```
 
    1. Lists are typed as indented
       paragraphs with:
       * a '*' or '-' (for bullet lists)
       * a digit followed by a period for
         numbered lists
```
Labeled lists (sometimes called description lists) are typed using square brackets for the label.
```
 
   [cat]   small domestic animal
   [+cat+] command to copy standard input
```
Labeled lists may also be produced by putting a double colon after the label. This sets the result in tabular form, so the descriptions all line up. This was used to create the 'author' block at the bottom of this description.
```
 
 cat:: small domestic animal
 +cat+:: command to copy standard input
```
For both kinds of labeled lists, if the body text starts on the same line as the label, then the start of that text determines the block indent for the rest of the body. The text may also start on the line following the label, indented from the start of the label. This is often preferable if the label is long. Both the following are valid labeled list entries:
```
 
 <tt>--output</tt> name [, name]::
 specify the name of one or more output files. If multiple
 files are present, the first is used as the index.
 
 <tt>--quiet:</tt>:: do not output the names, sizes, byte counts,
 index areas, or bit ratios of units as
 they are processed.
```

Headings are entered using equals signs

 
   = Level One Heading
   == Level Two Heading

and so on

Rules (horizontal lines) are entered using three or more hyphens.
Non-verbatim text can be marked up:

italic: word or text

bold: word or text

typewriter: word or <tt>text</tt>

The first form only words around 'words', where a word is a sequence of upper and lower case letters and underscores. Putting a backslash before inline markup stops it being interpreted, which is how I created the table above:
```
 
 _italic_:: \_word_ or \text
 *bold*:: \*word* or \text
 +typewriter+:: \+word+ or \<tt>text</tt>
```
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.
Hyperlinks to the web starting http:, mailto:, ftp:, or www. are recognized. An HTTP url that references an external image file is converted into an inline <IMG..>. Hyperlinks starting 'link:' are assumed to refer to local files whose path is relative to the --op directory.
Hyperlinks can also be of the form label[url], in which case the label is used in the displayed text, and url is used as the target.
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 modifier. These appear immediately after the start of the document element they are modifying. Other modifiers include
:nodoc:[all]
don't include this element in the documentation. For classes and modules, methods, aliases, and attributes directly within the affected class 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.
```
 
     module SM  #:nodoc:
       class Input
       end
     end
     module Markup #:nodoc: all
       class Output
       end
     end
```
In the above code, only class SM::Input will be documented.
:doc:
force a method to be documented even if it wouldn't otherwise be. Useful is, 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.
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.
 
    def get_dob(person)
       ...
```
Comment blocks can contain other directives:

: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).

:main:name
Equivalent to the --main command line parameter.

italic:	word or <em>text</em>
bold:	word or <b>text</b>
`typewriter`:	`word` or <tt>text</tt>