Headers are the building blocks of the documentation. Lets look at an example. The following header was taken from the documentation of the predecessor of ROBODoc, AutoDoc.

 /****f* financial.library/StealMoney
  *  NAME
  *    StealMoney -- Steal money from the Federal Reserve Bank. (V77)
  *  SYNOPSIS
  *    error = StealMoney( userName, amount, destAccount, falseTrail )
  *  FUNCTION
  *    Transfer money from the Federal Reserve Bank into the
  *    specified interest-earning checking account.  No records of
  *    the transaction will be retained.
  *  INPUTS
  *    userName    - name to make the transaction under.  Popular
  *                  favorites include "Ronald Reagan" and
  *                  "Mohamar Quadaffi".
  *    amount      - Number of dollars to transfer (in thousands).
  *    destAccount - A filled-in AccountSpec structure detailing the
  *                  destination account (see financial/accounts.h).
  *                  If NULL, a second Great Depression will be
  *                  triggered.
  *    falseTrail  - If the DA_FALSETRAIL bit is set in the
  *                  destAccount, a falseTrail structure must be
  *                  provided.
  *  RESULT
  *    error - zero for success, else an error code is returned
  *           (see financial/errors.h).
  *  EXAMPLE
  *    Federal regulations prohibit a demonstration of this function.
  *  NOTES
  *    Do not run on Tuesdays!
  *  BUGS
  *    Before V88, this function would occasionally print the
  *    address and home phone number of the caller on local police
  *    976 terminals.  We are confident that this problem has been
  *    resolved.
  *  SEE ALSO
  *    CreateAccountSpec(),security.device/SCMD_DESTROY_EVIDENCE,
  *    financial/misc.h
  ******
  * You can use this space for remarks that should not be included
  * in the documentation.
  */

A header consists of three different elements. A begin marker, a number of items, and an end marker. The begin marker in the example is example is:

  ****f* financial.library/StealMoney  

It marks the that marks the begin of a header. It also tells ROBODoc the name of the element that is being documented, StealMoney, the module it is part of, financial.library, and the kind of element, f, which stands for function. ROBODoc always expects a module name and an element name separated by a /. So ModFoo/funcBar is a valid name, but funcBar is not. See Sections for more information.

The end marker:

  ******

marks the end of a header.

Items begin with an item name and are followed by the item's body. An example:

  *  FUNCTION
  *    Transfer money from the Federal Reserve Bank into the
  *    specified interest-earning checking account.  No records of
  *    the transaction will be retained.

In this case the item's name is FUNCTION.

Each line of an item starts with a remark marker. In this case *.

The above example is a C example. ROBODoc supports many more languages though. The following table shows all the markers that ROBODoc supports by default.

/****       C, C++
 *
 ***/

//****      C++
//
//***

(****       Pascal, Modula-2
 *
 ***
 *)

{****       Pascal
 *
 ***
 *}

;****       M68K assembler
;
;***

****        M68K assembler, COBOL
*
***

C     ****  Fortran
C     
C     ***

REM ****    BASIC
REM *
REM ***

%****       LaTeX, TeX, Postscript
%
%***

#****       Tcl/Tk
#
#***

--****      Occam
--
--***

<!--****     HTML Code
*
***

<!---****    HTML Code
*
***

|****       GNU Assembler
|
|***

$!****      DCL
$!
$!***

'****       Visual Basic, Lotus script
'*
'***

.****       DB/C
.*
.***

!!****      FORTRAN 90
!!
!!***

!****       FORTRAN 90
!
!***

Any of these markers can be mixed, and they are not limited to the languages listed. So if you have a language that is not listed but that has remarks that start with a # you can use the Tcl/Tk markers, and create headers such as:

#****f* Foo/Bar
# FUNCTION
#   Bar snarfs the Foo input and mangles it.  Given the right settings
#   it might also do a bit of snu snu.
#***

ROBODoc defines a number of header types. You don't need to use them but they can be useful for sorting information. The headertype tells ROBODoc what kind of object you are documenting. This information allows ROBODoc to create more useful index tables.

The type is identified by one or two characters. ROBODoc expects to find them after the fourth * in the begin marker. So #****f is a valid marker, but #**f** is not.

If a single character is given, the type is defined as listed in the following table

If two characters are given, the first character should be i and the second can be any of the other characters from the table above. This creates an internal header of the type specified by the second character. Internal headers are special. They can be used to hide certain headers. They are only extracted if requested. You can use them to document internal functions, classes, etc. that you do not want clients to see, creating what might be a programmer's manual as opposed to a user's manual.

So /****if* Module/func1 defines an internal function called func1.

Headers marked internal are by default not included in the generated documentation. If you want to include them use the option --internal. You can also generate the documentation from only the internal headers with the option --internalonly.

You can define your own headertypes using the ROBODoc configuration file, robodoc.rc. See Customizing ROBODoc. This way you can document anything you like, for instance makefile entries, system tests, or exceptions.

By default ROBODoc recognizes the following items:

You can define your own items using the ROBODoc configuration file, robodoc.rc. See Customizing ROBODoc.

The structure of source code for an project is usually hierarchical. A project might consists of several applications, an application of several modules, a module of several functions or even submodules. ROBODoc allows you to show this hierarchy in your documentation. For this you specify the hierarchy in the header name. For instance, you have a project that is going to create a new language called D. The D Language project might consists of three applications: a preprocessor, a compiler, and a linker. The compiler consists of two modules, a parser and a generator. The parser module consists of several functions.

The following three headers show how this hierarchy can be defined in the header name.

#****h* D-Language/Compiler
# FUNCTION
#   The compiler takes a preprocessed source file and
#   turns it into an object file.
#***

#****h* D-Language/Linker
# FUNCTION
#   The linker module contains functions that scan a 
#   object file and build the executable.
#***

#****h* Compiler/Parser
# FUNCTION
#   The parser module contains functions that scan a 
#   preprocessed source file and build the syntax tree.
#***

#****f* Parser/ReadToken
# FUNCTION
#   ReadToken reads the next token from the input
#   file.
#***

When you generate documentation with the option --section, ROBODoc uses the hierarchical information when generating the table of content and document section information. For instance in HTML sections are started with <H1>, <H2>, <H3> depending on the level in the hierarchy. The table of will also contain levels. The table of contents for the above example will be:

1. D-Language/Compiler
1.1 Compiler/Parser
1.1.1 Parser/ReadToken
2. D-Language/Linker

By default ROBODoc creates preformatted text in the output documentation for all the text it finds in an item. This means that the formatting of the output looks the same as the formatting of the text of an item. Line-breaks and indentation stay the same. This is easy but does not always creates the best looking output.

ROBODoc can also try to deduce the formatting of your text based on the indentation of your text and on special characters in the text. It works a bit similar to the input method of Wikis.

You switch this on with the option --nopre. ROBODoc now tries to find three kind of elements: paragraphs, lists, and preformatted text.

Paragraphs are separated by empty lines. So the following item has two paragraphs.

  FUNCTION
    This function does something.

    And it then does something else
    and a bit more.

A List starts with a line that ends with a ':' which is then followed by one or more list items. List items should start with '*', '+', or 'o'. So the following item contains a valid list:

  FUNCTION
     This function does:
     * a lot of foo
     * some snafuing
     * and a bit of foobarring.

A list item can span than more line of the second and following lines are indented. So this is also a valid list:

  FUNCTION
     This function does:
     * a lot of foo and preprossesing of the 
       raw input with the aid of the some magic
     * some snafuing
     * and a bit of foobarring.

If listitems directly follow the name of a robodoc item they also form a valid list. So this is a valid list:

  INPUTS
    * inputname -- the name of the input file
    * outputname -- the name of the output file
    * n -- the number of characters to be written

Preformatted text is indicated by indenting it more that the surrounding text. The first non-empty line in an item determines the base indenting. Any lines with an indentation larger than this are preformatted. An example:

   FUNCTION
     The following lines are preformatted
        +--------+
        | A box  |
        |        |
        +--------+
     End of the preformatted text.

The following is complete example and its translation into HTML.

    This is some example text.
    And some more.

    This is even more, and we start a list:
    * a list item
    * a list item
    * a list item

    And we can also do preformatted stuff
    by indenting
        +--------+
        |        |
        +--------+
    The box will stay.

will be turn into

    <p>This is some example text.
    And some more.</p>

    <p>This is even more, and we start a list:</p>
    <ul>
    <li>a list item</li>
    <li>a list item</li>
    <li>a list item</li>
    </ul>

    <p>And we can also do preformatted stuff
    by indenting</p>
    <pre>
        +--------+
        |        |
        +--------+
    </pre>
    <p> The box will stay.</p>