Primeros pasos con doxygen

Instalación o Configuración

Instrucciones detalladas sobre cómo configurar o instalar doxygen.

Comentando tu código

Hay varias formas de marcar un bloque de comentarios como una descripción detallada, de modo que Doxygen analice este bloque de comentarios y lo agregue como una descripción del siguiente elemento de código a la documentación. El primero y más común son los comentarios de estilo C con un asterisco adicional en la secuencia de inicio del comentario, por ejemplo:

/**
 * … text …
 */
int dummy_var;

La siguiente alternativa es usar el estilo Qt y agregar un signo de exclamación (!) después de la secuencia de apertura de un bloque de comentarios de estilo C:

/*!
 * … text …
 */
void foo(void);

Una tercera alternativa es usar un bloque de al menos dos líneas de comentarios de C++, donde cada línea comienza con una barra oblicua adicional o un signo de exclamación:

/// 
/// ... text ... 
///

o

//! 
//! ... text ... 
//!

A algunas personas les gusta que sus bloques de comentarios sean más visibles en la documentación. Para este propósito puede utilizar lo siguiente:

 /********************************************//** 
  * ... text 
  ***********************************************/

Tenga en cuenta las 2 barras para finalizar el bloque de comentarios normal y comenzar un bloque de comentarios especial.

/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////

Para estructurar y formatear la documentación generada, Doxygen proporciona una gran cantidad (> 170) de comandos especiales. Todos los comandos en la documentación comienzan con una barra invertida () o un signo de arroba (@).

Por ejemplo

/**
 * \brief    A brief description in one short sentence.
 */

es equivalente a

/**
 * @brief    A brief description in one short sentence.
 */

Para la breve descripción también hay varias posibilidades:

Se podría usar el comando \brief con uno de los bloques de comentarios anteriores. Este comando termina al final de un párrafo, por lo que la descripción detallada sigue después de una línea vacía.

/** \brief Brief description. 
 * Brief description continued. 
 * 
 * Detailed description starts here. 
 */ 

Si JAVADOC_AUTOBRIEF se establece en en el archivo de configuración, el uso de bloques de comentarios de estilo JavaDoc iniciará automáticamente una breve descripción que termina en el primer punto seguido de un espacio o una nueva línea.

/// Brief description which ends at this dot. Details follow 
/// here. 

Y finalmente aquí un ejemplo para una documentación completa de una función con doxygen:

/**
 * \brief   The function bar. 
 *
 * \details This function does something which is doing nothing. So this text
 *          is totally senseless and you really do not need to read this,
 *          because this text is basically saying nothing.
 *
 * \note    This text shall only show you, how such a \"note\" section
 *          is looking. There is nothing which really needs your notice,
 *          so you do not really need to read this section.
 *
 * \param[in]     a    Description of parameter a.
 * \param[out]    b    Description of the parameter b.
 * \param[in,out] c    Description of the parameter c.
 *
 * \return        The error return code of the function.
 *
 * \retval        ERR_SUCCESS    The function is successfully executed
 * \retval        ERR_FAILURE    An error occurred
 */

errcode_t bar(int a, int b, int c)
{    
    /** More detailed description inside the code */
}

fuente y más información en la página de inicio de Doxygen