To document a block of code, the syntax we use is: 

/**
 * Documentation here.
 */

Doxygen will parse any comments located in such a block. Our style is to use as few Doxygen-specific commands as possible, so as to keep the source legible. Any mentions of functions or file names within the documentation will automatically link to the referenced code, so typically no markup need be introduced to produce links.

To document code inline, the syntax is: 

  // Hint, explanation, or reasoning here.

All documentation and comments always form proper sentences and use proper grammar and punctuation. ==Doxygen directives - general notes== {{ /**

  • Summary here; one sentence on one line (should not, but can exceed 80 chars). *
  • A more detailed description goes here. *
  • A blank line forms a paragraph. There should be no trailing white-space
  • anywhere. *
  • @param $first
  • "@param" is a Doxygen directive to describe a function parameter. Like some
  • other directives, it takes a term/summary on the same line and a
  • description (this text) indented by 2 spaces on the next line. All
  • descriptive text should wrap at 80 chars, without going over.
  • Newlines are NOT supported within directives; if a newline would be before
  • this text, it would be appended to the general description above.
  • @param $second
  • There should be no newline between multiple directives (of the same type).
  • @param $third
  • (optional) Boolean whether to do Third. Defaults to FALSE.
  • Only optional parameters are explicitly stated as such. The description
  • should clarify the default value if omitted. *
  • @return
  • "@return" is a different Doxygen directive to describe the return value of
  • a function, if there is any. */

function mymodule_foo($first, $second, $third = FALSE) { } }}}

Lists

 * @param $variables
 *   An associative array containing:
 *   - tags: An array of labels for the controls in the pager:
 *     - first: A string to use for the first pager element.
 *     - last: A string to use for the last pager element.
 *   - element: (optional) Integer to distinguish between multiple pagers on one
 *     page. Defaults to 0 (zero).
 *   Any further description - still belonging to the same param, but not part
 *   of the list.
 *
 * This no longer belongs to the param.

Lists can appear anywhere in Doxygen. The documentation parser requires you to follow a strict syntax to make them appear correctly in the parsed HTML output:

  • A hyphen is used to indicate the list bullet. The hyphen is aligned with (uses the same indentation level as) the paragraph before it, with no newline before or after the list.
  • No newlines between list items in the same list.
  • Each list item starts with the key, followed by a colon, followed by a space, followed by the key description. The key description starts with a capital letter.
  • If a list item exceeds 80 chars, it needs to wrap, and the following lines need to be aligned with the key (indented by 2 more spaces).
  • For text after the list that needs to be in the same block, use the same alignment/indentation as the initial text.
  • Again: within a Doxygen directive, or within a list, blank lines are NOT supported.
  • Lists can appear within lists, and the same rules apply recursively.

See Also sections

/**
 * (rest of function/file/etc. header)
 *
 * @see foo_bar()
 * @see ajax.inc
 * @see MyModuleClass
 * @see http://drupal.org/node/1354
 */

The @see directive may be used to link to (existing) functions, files, or URLs. @see directives should always be placed on their own line, and generally at the bottom of the documentation header. ==Links== 

/**
 * (rest of function/file/etc. header)
 *
 * See also @link group_name Link text @endlink
 */

The @link directive may be used to output a HTML link in line with the text, or to link to Doxygen groups that are defined elsewhere via @defgroup (see below). ==Automatic links== 

 * This function invokes hook_foo() on all implementing modules.

Any function, file, constant, etc. in the documentation will automatically be linked to the page where that item is documented (assuming that item has a doxygen header). For functions, you must include () after the function name to get the link. ==Code samples== 

 * Example usage:
 * @code
 *   mymodule_print('Hello World!');
 * @endcode
 * Text to immediately follow the code block.

Code examples can be embedded in the Doxygen documentation using @code and @endcode directives. Any code in between will be output preformatted. ==Todos== 

/**
 * @todo Remove this in D8.
 * @todo Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
 *   nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed
 *   diam voluptua.
 */

To document known issues and development tasks in code, @todo statements may be used. Each @todo should form an atomic task. They should wrap at 80 chars, if required. Additionally, any following lines should be indented by 2 spaces, to clarify where the @todo starts and ends. 

  // @todo Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
  //   nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
  //   sed diam voluptua.
  // We explicitly delete all comments.
  comment_delete($cid);

@todo statements in inline comments follow the same rules as above, especially regarding indentation of subsequent comments.

Grouping

Doxygen allows you to define groups of items, which show up on an API site as "Topics". Each group/topic generates a page, which contains some general information about the topic at the top, and then a list of the doxygen items (functions, files, etc.) that you've added to your group. 

Define a group with a @defgroup directive:

/**
 * @defgroup mymodule_validation Input validation
 * @{
 * Functions to validate user input.
 */

// Everything in here is automatically added to the group.

/**
 * @} End of "defgroup mymodule_validation".
 */

The @defgroup line gives the name of the group that will be used in the URL ("validation" here), and then the name that will be used as the page title ("Input validation" here). The @{ @} pair means that everything between them is automatically part of the group. Any text within the @defgroup's own doxygen header appears as text on the topic page.

If you have functions in multiple files that need to be added to a group, you can define the group as above in one file, and then use @ingroup to add individual other functions to the group: 

/**
 * Validates a foo.
 *
 * (rest of documentation header)
 *
 * @ingroup mymodule_validation
 */
function mymodule_validate_foo() {}

@ingroup lines should be added to the end of a documentation block, after any @see lines. It is recommended to leave a blank line between the @see section (if any) and the @ingroup section, although the blank line can be omitted if there is only one line of each.

If you have a larger group of functions that needs to be added to a group, you can use @addtogroup: 

/**
 * @addtogroup mymodule_validation
 * @{
 */

// Everything in here is added to the group.

/**
 * @} End of "addtogroup mymodule_validation".
 */

The "Limitations and hints" section at the bottom of this document has more information about grouping.