5.2 Using Doxygen source documentation system

1. Introduction

Doxygen is a tool that generates documentation from source code. Click here for the online Doxygen manual. The offline PDF manual is even better.

The comments embedded in the source code must be formatted in a special way, which may decrease readability for users not familiar with the special syntax. Markdown formatting is human readable and easy to grasp and has been included since Doxygen 1.8.0. Files with regular markdown syntax (as used by GitHub) are indicated with a *.md extension. Files using specialised Doxygen syntax are indicated with a *.dox extension.

The JavaDoc comment style was selected for this library. Although harder to type, an @ (at) character was selected to mark special commands instead of the \ (backslash) character to make these commands more prominent.

The Doxygen configuration file ("Doxyfile") can be found in the doc subdirectory. An excellent cross-platform Doxygen GUI frontend called doxywizard is included with the Doxygen package to manage settings and generate output. Each setting is meticulously documented in the wizard and configuration file.

Settings that differ from the default are highlighted in red.

2. Cheat sheet

This section provides a quick cheat sheet of the Doxygen documentation style selected for this library.

2.1 Brief description comment block

A brief comment block is marked with three slash characters (///). Example:

/// Size definition of the tick counter
typedef px_sysclk_ticks_t px_systmr_ticks_t;

2.2 Brief description comment block after a member

A brief comment after a member is indicated with three slash characters and a smaller than sign (///<). Example:

typedef struct
{
    px_systmr_state_t state;           ///< State of timer: STOPPED, STARTED or EXPIRED
    px_systmr_ticks_t start_tick;      ///< Tick when timer started
    px_systmr_ticks_t delay_in_ticks;  ///< Timer delay, used for subsequent timer restarts/resets
} px_systmr_t;

2.3 Detailed description comment block (using JavaDoc style)

The start of a detailed description comment block is indicated with a slash and double star sequence (/**). To make the block stand out as a unit, the star is continued at the start of each line. The JAVADOC_AUTOBRIEF setting is set to YES in the Doxygen configuration file ("px-fwlib/doc/Doxyfile"). With this setting a detailed description block always starts with a brief description. Example:

/** 
 *  Brief description which ends at this dot.
 *  
 *  Detailed description starts here.
 */

2.4 Special command prefix

All Doxygen special commands are prefixed with an @ (at) sign, for example @ingroup and @defgroup:

/**
 *  @ingroup COMMON
 *  @defgroup PX_TEMPLATE px_template.h : Template for a C module
 *
 *  Brief description (which ends at the dot).
 *
 *  Detailed description.
 */

2.5 Frequently used special commands

Here is a list of special commands that are used frequently in the library:

Command	Description
@ref	Add a hyperlinked reference to a named section, page or anchor
@param	Document a function parameter
@retval	Document the function return value
@ingroup	Make an entity a member of a specific group
@defgroup	Define a group
@addtogroup	Add additional members to a group

2.6 Function documentation

Here is an example that shows how a function, it's parameters and return value are documented:

/**
 *  See if a timer has expired.
 *
 *  @param systmr       Pointer to a timer object
 *
 *  @retval true        timer expired
 *  @retval false       timer not expired or timer stopped
 */
bool px_systmr_has_expired(px_systmr_t * systmr);

2.7 Module Grouping

C modules are documented in the H file using explicit grouping commands. The tree hierarchy is maintained in "px-fwlib/doc/module_tree.doc". Here is an example of the grouping at the start of the H file:

/** 
 *  @ingroup UTILS
 *  @defgroup PX_SYSTMR px_systmr.h : Polled software timers
 *  
 *  Brief description.
 *  
 *  Detailed description.
 *
 *  @{
 */
 
/// The number of timer ticks per second
#define TMR_TICKS_PER_SEC 100ul
 
/// @}

Observe that a @{ start marker and a @} end marker is used to indicate that all of the definitions, typedefs, variables and functions in between are part of that group.

2.8 Page Grouping

Documentation pages are grouped into sections and sub sections by refering to a child page anywhere on the parent page using the @subpage command.

For example "px-fwlib/doc/5___best_practice.dox":

# 5. Recommended best practices # {#BEST_PRACTICES}
 
- C coding style:
    + @subpage CODING_STYLE
- Doxygen as source documention tool:
    + @subpage DOXYGEN
- Subversion (SVN) for revision control:
    + @subpage SUBVERSION
- Test function for each module