6.8 Special Documentation Blocks

A special documentation block is a C or C++ comment block with some additional markings, so that Doxygen knows it is a piece of documentation that needs to end up in the generated documentation.

Normally, Doxygen expects special documentation blocks to immediately precede the syntactic element being documented (Prefix). There is a mechanism to allow documentation to be placed after the element to be documented (Postfix). Prefix style comment blocks are described here, while postfix comment blocks are described in "Putting Documentation after Members" on page 66.

Each code item can have two types of descriptions. Together, a brief description and a detailed description form the documentation: Both are semantically optional. More than one brief or detailed description per code item, however, is not allowed. We require at least one of these descriptions to be present.

A brief description is short, usually a single line. A detailed description provides longer and more detailed documentation.

You may place these descriptions in a comment block in several ways:

  • Comment blocks will automatically start a brief description which ends at the first period followed by a space or new line. For example:

    /** Brief description which ends at this dot.
This sentence begins the detailed description. The detailed description
continues...
**/

  • The behavior also exists for multi-line special C++ comments:

    /// Brief description which ends at this dot.
/// This sentence begins the detailed description.

It is preferred that any special documentation block longer than two lines use C-style commenting as shown in the first example above. While not required by Doxygen, we require the blank line between the brief description and the detailed description.

Within the body of a C-style comment block, Doxygen will ignore any leading spaces and asterisks, '*'. This means that the first example could be rewritten as follows without any change in the generated documentation.

/** Brief description which ends at this dot.
 *
 * This sentence begins the detailed description. The detailed
 * description continues...
**/

This type of comment decoration is acceptable because the line of '*' along the left make it easier to determine the extent of the comment.

As you can see, Doxygen is quite flexible. For more information, see the full Doxygen documentation.