Using Doxygen source documentation system

Introduction

Doxygen is a tool that generates documentation from source code. This page provides a cheat sheet of the Doxygen documentation style used in the Piconomic C coding style.

"Unfortunately" the comments embedded in the source code must be formatted in a special way, which decreases readability for users not familiar with the special syntax. Doxygen is able to parse different comment styles and the JavaDoc style was selected, because more editors like the excellent Visual SlickEdit support it.

Doxygen cheat sheet:

Brief description comment block

    /// This is a brief comment

Brief description comment block after a member

    ///< This is a brief comment after a member

Detailed description comment block (using JavaDoc style)

Detailed description block always starts with a brief description.

/** 
 *  Brief description which ends at this dot. Detailed description
 *  follows after the dot.
 *
 *  Detailed description continues.
 */

Command prefix

All Doxygen commands are prefixed with an @ sign, e.g. @defgroup

    /// Macro used to calculated @b x and @b y coordinates

Brief command list

• @ingroup - make an entity a member of a specific group
• @defgroup - define a group
• @addtogroup - add aditional members to a group
• @par - starts a paragraph with a user defined heading
• @code and @endcode - mark text as a block of code
• @param - document a function parameter
• @return and/or @retval - document the function return value

Function documentation

/** 
 *  See if a timer has expired.
 *  
 *  @param[in,out]  tmr   Pointer to a timer object
 *  
 *  @retval TRUE    timer expired
 *  @retval FALSE   timer not expired or timer stopped
 */
extern bool_t tmr_has_expired(tmr_t* tmr);

Grouping

C modules are documented using grouping mechanisms

/** 
 *  @ingroup GENERAL
 *  @defgroup TMR tmr.h : Polled software timers
 *    
 *  Brief description.
 * 
 *  Detailed description.
 * 
 *  @{
 */

/// The number of timer ticks per second
#define TMR_TICKS_PER_SEC 100ul

/**
 *  @}
 */