Looking for doxygen Answers? Try Ask4KnowledgeBase
Looking for doxygen Keywords? Try Ask4Keywords

doxygenEmpezando con doxygen


Observaciones

Esta sección proporciona una descripción general de qué es doxygen y por qué un desarrollador puede querer usarlo.

También debe mencionar cualquier tema grande dentro de doxygen, y vincular a los temas relacionados. Dado que la Documentación para doxygen es nueva, es posible que deba crear versiones iniciales de los temas relacionados.

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. Los primeros y más comunes son los comentarios de estilo C con un asterisco adicional en la secuencia de inicio de comentarios, 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 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 puedes usar lo siguiente:

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

Tenga en cuenta las 2 barras diagonales para finalizar el bloque de comentarios normal e iniciar un bloque de comentarios especial.

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

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

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 YES 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í hay 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 principal de Doxygen.

Instalación o configuración

Instrucciones detalladas sobre cómo configurar o instalar doxygen.