Débuter avec doxygen

Installation ou configuration

Instructions détaillées sur la configuration ou l’installation de doxygen.

Commentant votre code

Il existe plusieurs façons de marquer un bloc de commentaires comme une description détaillée, afin que ce bloc de commentaires soit analysé par Doxygen et ajouté en tant que description de l’élément de code suivant à la documentation. Le premier et le plus courant sont les commentaires de style C avec un astérisque supplémentaire dans la séquence de début du commentaire, par exemple :

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

L’alternative suivante consiste à utiliser le style Qt et à ajouter un point d’exclamation (!) après la séquence d’ouverture d’un bloc de commentaires de style C :

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

Une troisième alternative consiste à utiliser un bloc d’au moins deux lignes de commentaire C++, où chaque ligne commence par une barre oblique supplémentaire ou un point d’exclamation :

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

ou

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

Certaines personnes aiment rendre leurs blocs de commentaires plus visibles dans la documentation. A cet effet, vous pouvez utiliser les éléments suivants :

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

Notez les 2 barres obliques pour terminer le bloc de commentaires normal et commencer un bloc de commentaires spécial.

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

Pour structurer et formater la documentation générée, Doxygen fournit un grand nombre (> 170) de commandes spéciales. Toutes les commandes de la documentation commencent par une barre oblique inverse () ou un arobase (@).

Par exemple

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

est équivalent à

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

Pour la brève description il y a aussi plusieurs possibilités :

On pourrait utiliser la commande \brief avec l’un des blocs de commentaires ci-dessus. Cette commande se termine à la fin d’un paragraphe, donc la description détaillée suit après une ligne vide.

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

Si JAVADOC_AUTOBRIEF est défini sur YES dans le fichier de configuration, l’utilisation de blocs de commentaires de style JavaDoc lancera automatiquement une brève description qui se termine au premier point suivi d’un espace ou d’une nouvelle ligne.

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

Et enfin voici un exemple pour une documentation complète d’une fonction avec 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 */
}

source et plus d’informations sur la [page d’accueil de Doxygen][1]

[1] : http://www.stack.nl/~dimitri/doxygen/manual/index.html