Table of Contents
Assertions make for great comments! A nicely written expression can tell a developer exactly what they should expect at a given point in the code. Developers should architect their assertions to give a clearer understanding of what is happening in the system which in turn will help decrease bugs.
Pre-conditions and post-conditions should be checked with assertions.
Doxygen notes are provided for the following areas:
This tag supplies a brief description of a function for Doxygen pages. This message should tell what happens in the function. Briefs are included in the header file along with the declaration of the functions.
This tag supplies a more detailed description. This message should give a user an idea of:
- when it is valid to call this function
- i.e., what must be true for the function to work
- how the function carries out it purpose
- what will be true when the function returns
This tag can be used to document the purpose and meaning of parameters for functions. You can specify the nature of the param as input, output, or both in the following manner:
@param[in]@param[out]@param[in/out]
This tag informs Doxygen that the comment block should be associated with the class. This block should explain the purpose of the class, the design considerations, and relation to other classes. Also provide any information other programmers may find useful for using the classes.
This tag allows you to insert code snippets which are then collected on the examples page. This way you can tell people how to use your code directly in the file with your class definition.
This tag allows you to describe what the function is returning.
This tag tells Doxygen that this is a free floating page. Doxygen will name the page so that other pages can reference and link to the page.
@page using_a_platform Using a Platform
The first word after @page is the word that will need to be type in a @ref command to link the page. Doxygen will replace any references to the page with the string that appears after the word. So in the above case Doxygen would replace "using_a_platform" with "Using a Platform" in the generated documentation.
This command tells Doxygen to insert a link to the specified page in this section. If you wanted to insert a link to the page describing how to use a platform, you would type:
// Links to page defined above
///// @ref using_a_platform
This tag allows one to insert an image into the documentation. Doxygen requires different image formats for the different output types. Below I show how to insert images such that they appear in both html and pdfs generated by latex. Note that the image files must be placed in a location recognized by Doxygen. This is set by the IMAGE_PATH variable in the Doxygen file. Currently the docs/images folder is indexed. So placing the image files in that location should allow Doxygen to find them.
///// @image html special_image.png
///// @image latex special_image.eps "Special Image label" width=5cm
It is often useful to divide a Doxygen page into sections and subsections. The serves two purposes. One it creates headers. Second reference can be created to through the page to link to the section. This page makes of sections and links to sections. The list of section at the beginning of the page is implemented using the @section command. Similar to the @page command, a link name and string can be provided.
///// @section common_Doxygen_tags_used Common Doxygen Tags
///// @subsection common_page_tags Common Doxygen Page Tags
Markdown heading tags can also be used (# Header 1, ## Subsection of Header 1, etc.)
Starts a paragraph where the postcondition of an entity can be described. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent \post commands will be joined into a single paragraph. Each postcondition will start on a new line. Alternatively, one \post command may mention several postconditions. The \post command ends when a blank line or some other sectioning command is encountered.
@post Post condition documentation here.
Starts a paragraph where the precondition of an entity can be described. The paragraph will be indented. The text of the paragraph has no special internal structure. All visual enhancement commands may be used inside the paragraph. Multiple adjacent \pre commands will be joined into a single paragraph. Each precondition will start on a new line. Alternatively, one \pre command may mention several preconditions. The \pre command ends when a blank line or some other sectioning command is encountered.
@pre Pre-condition documentation here.
There are two grouping mechanisms in Doxygen:
- Modules, which group things together on a separate page
- Member Groups, which group functions together on a class/module/namespace page.
Modules are a way to group things together on a separate page. You can document a group as a whole, as well as all individual members. Members of a group can be files, namespaces, classes, functions, variables, enumerations, typedefs, and defines, but also other groups.
To define a group, you should put the @defgroup command in a special comment block. The first argument of the command is a label that should uniquely identify the group. You can make an entity a member of a specific group by putting a @ingroup command inside its documentation block. The second argument is the title of the group.
To avoid putting @ingroup commands in the documentation of each member you can also group members together. Place the open marker @{ before the group and the closing marker @} after the group. The markers can be put in the documentation of the group definition or in a separate documentation block.
Groups can also be nested using these grouping markers.
You will get an error message when you use the same group label more than once. If you don't want Doxygen to enforce unique labels, then you can use \addtogroup instead of \defgroup. @addtogroup can be used exactly like \defgroup. When the group has been defined already, then it silently merges the existing documentation with the new one. The title of the group is optional for this command. You can use the following to add members to a group that is defined in more detail elsewhere.
/** \addtogroup <label> */
/*\@{*/
/*\@}*/
Compound entities (like classes, files and namespaces) can be put into multiple groups. Members (e.g., variable, functions, typedefs and enumerations) can only be a member of one group.
If a compound (e.g., a class or file) has many members, it is often desired to group them together. Doxygen already automatically groups things together on type and protection level. Maybe you feel that this is not enough or that that default grouping is wrong. For example, members of different syntactic types might belong to the same semantic group.
A member group is defined by a
//@{
...
//@}
block or a
/*@{*/
...
/*@}*/
block if you prefer C style comments. Note that the members of the group should be physically inside the member group's body.
Before the opening marker of a block a separate comment block may be placed. This block should contain the @name (or \name) command and is used to specify the header of the group. Optionally, the comment block may also contain more detailed information about the group.
Nesting of member groups is not allowed.
If all members of a member group have the same type and protection level, then the group is displayed as a subgroup. For example, the group is displayed as a subsection of the "Static Public Members" section. If two or more members have different types, then the group is put at the same level as the automatically generated groups. Put a \nosubgrouping command inside the documentation of the class to force all member-groups of a class to be at the top level.
Doxygen also supports @ref inside a link definition:
[myclass]: @ref MyClass "My class"
Markdown syntax for images is similar to that for links. The only difference is an additional ! before the link text. Examples:
![Caption text][img def]
![img def]
[img def]: /path/to/img.jpg "Optional Title"
Also here you can use @ref to link to an image:
![img def]
[img def]: @ref image.png "Caption text"
The caption text is optional.
Automatic Linking
To create a link to an URL or e-mail address Markdown supports the following syntax:
<http://www.example.com>
<https://www.example.com>
<ftp://www.example.com>
<mailto:address@example.com>
<address@example.com>
Note that Doxygen will also produce the links without the angle brackets.
Doxygen supports a special link marker [TOC]. This marker can be placed in a page to produce a table of contents at the start of the page. All sections will be listed.
Note that using [TOC] is the same as using a \tableofcontents command.
Note that the TOC_INCLUDE_HEADINGS has to be set to a value > 0 otherwise no table of contents is shown when using Markdown Headers.
Of the features defined by "Markdown Extra" is support for tables. A table consists of a header line, a separator line, and at least one row line. Table columns are separated by the pipe (|) character.
Here is an example:
First Header | Second Header
------------- | -------------
Content Cell | Content Cell
Content Cell | Content Cell
Column alignment can be controlled via one or two colons at the header separator line:
| Right | Center | Left |
| ----: | :----: | :---- |
| 10 | 10 | 10 |
| 1000 | 1000 | 1000 |
Additionally, column and row spans are supported. Using a caret ("^") in a cell indicates that the cell above should span rows. Sequences of carets may be used for any number of row spans. For example:
| Right | Center | Left |
| ----: | :----: | :---- |
| 10 | 10 | 10 |
| ^ | 1000 | 1000 |
Column spans are supported by means of directly adjacent vertical bars ("|"). Each additional vertical bar indicates an additional column to be spanned. To put it another way, a single vertical bar indicates a single column span, two vertical bars indicates a 2 columns span, and so on. For example:
| Right | Center | Left |
| ----: | :----: | :---- |
| 10 | 10 | 10 |
| 1000 |||
Standard Markdown has no support for labeling headers, which is a problem if you want to link to a section.
Markdown Extra allows you to label a header by adding the following to the header:
Header 1 {#labelid}
========
## Header 2 ## {#labelid2}
To link to a section in the same comment block you can use
[Link text](#labelid)
to link to a section in general, Doxygen allows you to use @ref
[Link text](@ref labelid)
Note this only works for the headers of level 1 to 4.
Doxygen can process files with Markdown formatting. For this to work the extension for such a file should be .md or .markdown (see EXTENSION_MAPPING if your Markdown files have a different extension, and use md as the name of the parser). Each file is converted to a page (see the page command for details).
By default the name and title of the page are derived from the file name. If the file starts with a level 1 header however, it is used as the title of the page. If you specify a label for the header (as shown in Header Id Attributes) Doxygen will use that as the page name. If the label is called "index" or "mainpage" Doxygen will put the documentation on the front page (index.html).
Here is an example of a file README.md that will appear as the main page when processed by Doxygen:
My Main Page {#mainpage}
============
Documentation that will appear on the main page
If a page has a label you can link to it using @ref as is shown above. To refer to a markdown page without such label you can simple use the file name of the page, e.g.
See [the other page](other.md) for more info.
Special care has to be taken when using *'s in a comment block to start a list or make a ruler.
Doxygen will strip off any leading *'s from the comment before doing Markdown processing. So although the following works fine
/** A list:
* * item1
* * item2
*/
When you remove the leading *'s Doxygen will strip the other stars as well, making the list disappear!
Rulers created with *'s will not be visible at all. They only work in Markdown files.
Groups can be nested. When you declare a group, you can use the @ingroup command to add that
group to another. For example, this declaration creates a tier of three groups:
/** \defgroup GROUP_A My top-level group description
*
* Put here a longer description.
*
**/
/** @addtogroup GROUP_B My group B description
* \ingroup GROUP_A
* @{ */
// classes, etc.
/** @} */
/** @addtogroup GROUP_C My group C description
* \ingroup GROUP_B
* @{ */
// classes, etc.
/** @} */
When Doxygen parses the source code it first extracts the comments blocks, then passes these through the Markdown preprocessor. The output of the Markdown preprocessing consists of text with special commands and HTML commands. A second pass takes the output of the Markdown preprocessor and converts it into the various output formats.
During Markdown preprocessing no errors are produced. Anything that does not fit the Markdown syntax is simply passed on as-is. In the subsequent parsing phase this could lead to errors, which may not always be obvious as they are based on the intermediate format.
To see the result after Markdown processing you can run Doxygen with the -d Markdown option. It will then print each comment block before and after Markdown processing.