doxygenDémarrer avec doxygen
Remarques
Cette section fournit une vue d'ensemble de ce qu'est doxygen et pourquoi un développeur peut vouloir l'utiliser.
Il devrait également mentionner tous les grands sujets dans le doxygen, et établir un lien avec les sujets connexes. La documentation de doxygen étant nouvelle, vous devrez peut-être créer des versions initiales de ces rubriques connexes.
Commenter votre code
Il existe plusieurs façons de marquer un bloc de commentaires comme une description détaillée, de sorte 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 commun 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 commentaires 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. Pour cela, vous pouvez utiliser les éléments suivants:
/********************************************//**
* ... text
***********************************************/
Notez les 2 barres obliques pour terminer le bloc de commentaires normal et démarrer un bloc de commentaires spécial.
/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////
Pour structurer et créer 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 signe (@).
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 existe également 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, de sorte que la description détaillée suit 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 terminera 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'infos sur la page d'accueil de Doxygen
Installation ou configuration
Instructions détaillées sur l'installation ou l'installation du doxygen.
