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.

  1. Lists are typed as indented paragraphs with:

    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
    
  2. Labeled lists (sometimes called description lists) are typed using square brackets for the label.
     
       [cat]   small domestic animal
       [+cat+] command to copy standard input
    
  3. 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> <i>name [, name]</i>::
           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.
    
  4. Headings are entered using equals signs
     
       = Level One Heading
       == Level Two Heading
    

    and so on

  5. Rules (horizontal lines) are entered using three or more hyphens.
  6. Non-verbatim text can be marked up:
    italic:word or <em>text</em>
    bold:word or <b>text</b>
    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 \<em>text</em>
      *bold*::       \*word* or \<b>text</b>
      +typewriter+:: \+word+ or \<tt>text</tt>
    
  7. 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.
  8. 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.

  9. 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| ... }
    
  10. ':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.
  11. 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)
           ...
    
  12. 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.