Writing Documentation¶

Entities in C++ source code (e.g. classes, functions, operators, variables, macros) are documented by adding a documentation comment immediately before or after their declaration. Various conventions are supported to distinguish documentation comments from regular comments. The most basic is to put the comment immediately before the declaration style it as /** ... */ rather than /* ... */. The contents of the documentation can be formatted with Markdown, and include various commands using the syntax @command.

Example

/**
 * An example class with documentation. It might include a list:
 * 
 * - first item,
 * - second item, and
 * - third item,
 *
 * or even a table:
 *
 * | Heading 1 | Heading 2 |
 * | --------- | --------- |
 * | Content 1 | Content 2 |
 */
class Example {
  //
};

/**
 * An example function with documentation. This time we use commands.
 *
 * @param x First argument.
 * @param y Second argument.
 *
 * @return The result.
 */
int f(int x, int y);

If the documentation is placed immediately before the declaration of an entity, the following styles are supported:

/** ... */
/*! ... */
/// ...
//! ...

If the documentation is placed immediately after the declaration, e.g. as an end-of-line comment, the following styles are supported:

/**< ... */
/*!< ... */
///< ...
//!< ...

Example

enum Example {
  FIRST,   ///< First possible value
  SECOND,  ///< Second possible value
  THIRD,   ///< Third possible value
};

Commands¶

The suggestion is to use Markdown wherever possible when writing documentation comments. Doxide provides a small set of commands that can be used to organize documentation (e.g. @ingroup) and to ensure consistent formatting for common elements (e.g. @param).

Command	Description
`@param name`, `@param[in] name`, `@param[out] name`, `@param[in,out] name`	Document parameter `name`. The following paragraph is the description. The additional annotations `[in]`, `[out]` and `[in,out]` mark the parameter as an input (default), output or both input and output parameter. The following paragraph is the description.
`@tparam`	Document a template parameter `name`.
`@return`	Document the return value with the following paragraph.
`@pre`, `@post`	Document pre- or post-conditions with the following paragraph.
`@throw name`	Document an exception `name` with the following paragraph.
`@see`	Add a paragraph of "see also" references. The references themselves can be formatted in Markdown, using links if desired.
`@anchor name`	Insert anchor that can be linked to from elsewhere with the Markdown syntax `[text](#name)`.
`@ingroup name`	Add the entity to the group `name`. See organizing for more information.
`@@`	Escape: replaced with a single `@`.
`@/`	Escape: replaced with a single `/`.

Tip

As a particular use case, comments within documentation comments are possible by escaping the closing sequence */ as *@/. This can be useful when providing example code within a documentation comment.

Migration support¶

To assist in the migration of existing code bases to Doxide from other documentation tools, some additional support is provided:

The character \ may be used as an alternative to @ to denote commands. When \ is used, unlike when @ is used, no warning is given if the command is not found, and the command is output as-is. This is necessary to support LaTeX macros in mathematics without warning overload.
The character % may be used as an escape for a single non-whitespace character (it is used to break automatic linking in Doxygen).

The following behaviors are implemented to assist in the migration of existing code bases. Recommended alternatives are provided for new code bases.

Command(s)	Doxide behavior	Recommended alternative
`@e word`, `@em word`, `@a word`	Replace with Markdown.	Use Markdown emphasis: `word`
`@b word`	Replace with Markdown.	Use Markdown bold: `word`
`@c word`, `@p word`	Replace with Markdown.	Use Markdown inline code: `word`
`@f$ ... @f$`	Replace with Markdown.	Use Markdown inline math: $ ... $
`@f\[ ... @f]`	Replace with Markdown.	Use Markdown display math: `$$ ... $$`.
`@li`, `@arg`	Replace with Markdown.	Use Markdown unordered list item: `-`
`@code ... @endcode`, `@verbatim ... @endverbatim`	Replace with Markdown.	Use Markdown display code: ``` ... ```.
`@attention`, `@bug`, `@example`, `@note`, `@todo`, `@warning`, `@remark`, `@remarks`	Replace with Markdown.	Use Markdown admonition: `!!! type`.
`@ref name text`	Replace with Markdown.	Use Markdown link: `[text](#name)`
`@image format file alt`	Ignored.	Use Markdown image: `![alt](file)`
`@returns`, `@result`	As `@return`.	Use `@return`.
`@throws` , `@exception`	As `@throw`.	Use `@throw`.
`@sa`	As `@see`.	Use `@see`.
`@brief`, `@short`	Ignored.	Make the first sentence of the documentation comment usable as a brief description.
`@internal`	Documentation comment and entity are hidden.	Use a normal comment, rather than a documentation comment.
`@defgroup`	Ignored.	Doxide handles groups differently, see below.
`@file`	Ignored.	Doxide does not produce documentation for files. Incorporate into the documentation for another entity, or into a custom page.
`@def MACRO`	Ignored.	Doxide does not run the preprocessor. Add a documentation comment immediately before the `#define`.
`@var name`, `@fn name`, `@class name`, `@struct name`, `@union name`, `@enum name`, `@typedef name`, `@namespace name`, `@interface name`, `@protocol name`, `@property name`.	Ignored.	Add a documentation comment immediately before the relevant entity.