6.10 Special Commands

All Doxygen commands start with an "at" sign (@). A commands may have one or more arguments. The following typographic conventions are used to identify each arguments range:

• If <sharp> braces are used, the argument is a single word.

• If (round) braces are used, the argument extends until the end of the line on which the command was found.

• If {curly} braces are used, the argument extends until the next paragraph. Paragraphs are delimited by a blank line or by a section indicator.

• If [square] brackets are used, the argument is optional.

The following sections describe the special Doxygen commands.

6.10.1 @example

Indicates that a comment block contains documentation for a source code example.

6.10.2 @file [ ]

Indicates that a comment block contains documentation for a source or header file with name . If the file name is omitted, Doxygen uses the name of the file that contains the @file command. This is the preferred method.

6.10.3 @attention { attention text }

Starts an indented paragraph where you can enter a message about an issue that needs attention.

6.10.4 @param[in,out] { parameter description }

Starts a parameter description for a function parameter named .

6.10.5 @post { description of a postcondition }

Starts an indented paragraph where you can describe a postcondition of an entity.

6.10.6 @pre { description of a precondition }

Starts an indented paragraph where you can describe a precondition of an entity.

6.10.7 @retval { description }

Starts a description of a return value from a function. Include a separate @retval for each unique return value.

6.10.8 @return { description of what is returned }

Starts a description for a function's return values when those values aren't easily described by @retval commands (that is, the return values are something other than a small set of unique values with discrete meanings).

6.10.9 @sa { references }

Starts a paragraph where you can specify one or more cross-references to functions, structures, variables, files, or URLs.

6.10.10 @since { text }

This tag can be used to specify when (version or time) an entity is available.

6.10.11 @test { paragraph describing a test case }

Starts a paragraph where you can describe a test case. The description will also add the test case to a separate test list. The two instances of the description will be cross-referenced. Each test case in the test list will be preceded by a header that indicates the origin of the test case.

6.10.12 @todo { paragraph describing what is to be done }

Starts a paragraph where a TODO item is described. The description will also add an item to a separate TODO list. The two instances of the description will be cross-referenced. Each item in the TODO list will be preceded by a header that indicates the origin of the item.

6.10.13 HTML Commands

For greater control over the format of generated documentation, you may add HTML commands to special documentation blocks. "HTML Character Entities" below lists the special HTML character entities that Doxygen recognizes.

"HTML Commands" lists the HTML commands that you may use inside the documentation.

Finally, to put invisible comments inside comment blocks, you may use HTML style comments:

/** <!-- This is a comment within a comment block --> Visible text */

Table 11 HTML Character Entities

Table 12 HTML Commands