This is a Work in Progress

Doxygen Comments

Doxygen reads specially formatted comment blocks and turns them into documentation.

The Doxygen documentation lists all the possible commands. Some common ones are:

  • @param – a function parameter
  • @struct – a C-struct.
  • @union – a union.
  • @enum – an enumeration type.
  • @var – a variable or typedef or enum value.
  • @def – a #define.
  • @typedef – a type definition.
  • @file – a file.

Functions

Here’s a basic template for a function comment. It begins with two asterisks.

/**
 * FUNCTION-NAME - ONE LINE DESCRIPTION OF FUNCTION
 * @param NAME1 SHORT-DESC
 * @param NAME2 SHORT-DESC
 * ...
 *
 * @return DESC-OF-RETURN-VALUE
 *
 * LONG DESCRIPTION
 */

The @param can have an optional suffix indicating the direction:

  • [in] – a normal inbound parameter
  • [out] – an “out-param” (a value passed to the caller)
/**
 * Turn a number into text
 * @param[in]  num  Number to be converted
 * @param[out] ptr  Where to store the new string
 *

The return value @return could be descriptive, e.g. “Number of apples”, or a list of possible values.

Here, we have XXX inserted and extra * to make the text into a list (in Markdown).

 *
 * @retval  0:  Error
 * @retval  n:  Success
 *

Here’s an example function comment block from sidebar.c:

/**
 * draw_divider - Draw a line between the sidebar and the rest of mutt
 * @param num_rows  Height of the Sidebar
 * @param num_cols  Width of the Sidebar
 *
 * @retval  0:  Empty string
 * @retval  n:  Divider occupies n screen columns
 *
 * Draw a divider using characters from the config option "sidebar_divider_char".
 * These can be an ASCII or Unicode characters.
 * We calculate these characters' width in screen columns.
 *
 * If the user hasn't set $sidebar_divider_char we pick a character for them,
 * respecting the value of $ascii_chars.
 */
static int draw_divider(int num_rows, int num_cols)

Search by Algolia