Doxygen formatting highlights

in

source

Developer documentation » Coding standards » Doxygen formatting conventions

Documenting files

It is good practice to provide a comment describing what a file does at the start of it. For example:

<?php
// $Id: theme.inc,v 1.202 2004/07/08 16:08:21 dries Exp $

/**
 * @file
 * The theme system, which controls the output of Drupal.
 *
 * The theme system allows for nearly all output of the Drupal system to be
 * customized by user themes.
 */

Documenting functions

All functions that may be called by other files should be documented; private functions optionally may be documented as well. A function documentation block should immediately precede the declaration of the function itself, like so:

/**
 * Verify the syntax of the given e-mail address.
 *
 * Empty e-mail addresses are allowed. See RFC 2822 for details.
 *
 * @param $mail
 *   A string containing an email address.
 * @return
 *   TRUE if the address is in a valid format.
 */
function valid_email_address($mail) {

Functions that are easily described in one line may omit these directives, as follows:

/**
 * Convert an associative array to an anonymous object.
 */
function array2object($array) {

Documenting hook implementations

If the implementation is rather standard and does not require more explanation than the hook reference provides, a shorthand documentation form may be used:

/**
 * Implementation of hook_help().
 */
function blog_help($section) {

Documenting forms

In order to provide a quick reference for themers, we tag all form builder functions so that Doxygen can group them together. The form builder function is defined as any function meant to be used as an argument for drupal_get_form.

/**
 * FAPI definition for the user login form.
 *
 * ...
 * @ingroup forms
 * @see user_login_default_validators()
 * @see user_login_submit()
 */
function user_login(&$form_state, $msg = '')

Documenting theme templates

If a template and a preprocess function is used instead of a theming function, an empty function definition of the theme function that is not used should be placed in the contributed documentation (contributions/docs/developer/theme.php).

<?php
// $Id$

/**
 * @file forum_list.tpl.php
 * Default theme implementation to display a list of forums.
 *
 * Available variables:
 * - $forums: An array of forums to display.
 *
 * Each $forum in $forums contains:
 * - $forum->is_container: Is TRUE if the forum can contain other forums. Is
 *   FALSE if the forum can contain only topics.
 * - $forum->depth: How deep the forum is in the current hierarchy.
*
 * @see template_preprocess_forum_list()
 */

Documenting contributed modules and themes

  • If you use Doxygen Modules, make sure you give them a unique namespace, which would be your module's name. E.g. @defgroup views ... for the views.module, @defgroup views_ui ... for the views_ui.module. Don't use group names which are defined in Drupal core (hooks, themeable, file, batch, database, forms, form_api, format, image, validation, search, etc.).

A recommended way of using Doxygen grouping in contributed modules and themes is the following:

in your main example.module:

/**
 * @defgroup example Example: short description of your module
 *
 * Longer description of your module, including all other files and modules.
 */
 
/**
 * @file
 *
 * Description of your module's main file.
 *
 * @ingroup example
 */

in the other modules and code files of your module:

/**
 * @file
 *
 * Description of another file in your module.
 *
 * @ingroup example
 */

Limitations and hints

Drupal's Doxygen processing module, api.module, currently only supports a small subset of all Doxygen commands and makes some assumptions about the formatting of the source. Code to be processed by api.module is advised to stick to these conventions.

Api.module currently supports only one of Doxygen's three grouping mechanisms: Modules (@defgroup, @ingroup, @addtogroup, @{, @}). When using those, please note the following:

  • Modules work at a global level, creating a new page for each group. They should be used only to group functions that provide some kind of API, which possibly spans multiple files. Or the other way round: they should not be used to group functions in a file when these functions are only used in that very file. Thats what Member Groups are for (which unfortunately aren't supported by api.module yet).
  • @defgroups can be defined only once - trying to define a second @defgroup name with a name already used will result in an error. Use @defgroup name in the "most important" section/file of that group and add to it from other places with @addtogroup / @ingroup.
  • The name in @defgroup name Explaination of that group must be single-word identifier, like a PHP variable or function name. Or, as regular expression: [a-zA-Z_][a-zA-Z0-9_]*. Dots, hyphens, etc. are not allowed.

To see how a real Doxygen processes and displays the current Drupal code documentation (both core and contrib), have a look at ax' Drupal site. Especially, look at the "doxygen error logs" and help improving Drupals code documentation.