Initiation à Doxygen pour C et C++

Date de publication : 19/09/2007

Par Franck Hecht (retour aux articles) (Blog)
 

Vous désirez créer de la documentation technique pour vos projets de développement ? Ce tutoriel va vous montrer la marche à suivre pour arriver à vos fins avec Doxygen !

Commentez cet article : 6 commentaires

I. Introduction

II. Les balises standards

Ce chapitre vous présente succinctement les balises les plus utilisées avec Doxygen. Pour la liste complète, rendez-vous sur le site officiel:  Special Commands

II-A. Les blocs de documentation

/**
 * ... Documentation ...
 */

/*!
 * ... Documentation ...
 */

///
/// ... Documentation ...
///

//!
//! ... Documentation ...
//!

II-B. \file

\file [<name>]

\file main.c

II-C. \brief

\brief {brief description}

\brief Courte description.

\brief Courte description.
       Suite de la courte description.

II-D. \author

\author { list of authors }

\author Franck.H

II-E. \version

\version { version number }

\version 0.1

II-F. \date

\date { date description }

\date 10 septembre 2007

II-G. \struct

1. Nom de la structure
2. Nom du fichier d'en-tête (ex: le fichier où elle est définie)
3. Nom optionnel pour masquer le nom affiché par le second argument

\struct <name> [<header-file>] [<header-name>]

\struct Str_t

\struct Str_t str.h "Définition"

II-H. \enum

\enum <name>

\enum Str_err_e

II-I. \union

\union <name> [<header-file>] [<header-name>]

II-J. \fn

\fn (function declaration)

\fn int main (void)

Il est possible d'omettre cette balise lorsque le bloc de documentation commence juste au-dessus de la déclaration/définition de la fonction/méthode. Doxygen ajoutera de lui-même la signature de la fonction ou de la méthode. On peut donc en conclure que nous pouvons documenter une fonction à peu près n'importe où dans le code mais dans ce cas, il faut ajouter la balise !

II-K. \def

\def <name>

\def MAX(x,y)

II-L. \param

\param <parameter-name> { parameter description }

\param self Pointeur sur un objet de type Str_t.

\param[in] self Pointeur sur un objet de type Str_t.

Paramètres:
    [in] self Pointeur sur un objet de type Str_t.

II-M. \return

\return { description of the return value }

\return Instance de l'objet, NULL en cas d'erreur.

II-N. \bug

\bug { bug description }

\bug Problème d'affichage du texte en sortie

II-O. \deprecated

\deprecated { description }

\deprecated Fonction dépréciée, ne plus utiliser !

II-P. \class

\class <name> [<header-file>] [<header-name>]

\class Str

II-Q. \namespace

\namespace <name>

\namespace std

III. Mise en place de la documentation

III-A. Informations d'en-tête

/**
 * \file main.c
 * \brief Programme de tests.
 * \author Franck.H
 * \version 0.1
 * \date 11 septembre 2007
 *
 * Programme de test pour l'objet de gestion des chaînes de caractères Str_t.
 *
 */

III-B. Documentation d'une fonction/méthode

/**
 * \fn static Str_t * str_new (const char * sz)
 * \brief Fonction de création d'une nouvelle instance d'un objet Str_t.
 *
 * \param sz Chaîne à stocker dans l'objet Str_t, ne peut être NULL.
 * \return Instance nouvellement allouée d'un objet de type Str_t ou NULL.
 */

Remarquez que pour la balise \fn, il faut fournir la déclaration complète de la fonction ou de la méthode !

Il ne faut surtout pas oublier de bien fournir la balise \param car une vérification syntaxique de celle-ci sera faite par Doxygen et au moindre problème, il ne générera pas votre documentation !

III-C. Documentation d'une structure/union

/**
 * \struct Str_t
 * \brief Objet chaîne de caractères.
 *
 * Str_t est un petit objet de gestion de chaînes de caractères. 
 * La chaîne se termine obligatoirement par un zéro de fin et l'objet 
 * connait la taille de chaîne contient !
 */

typedef enum
{
   STR_NO_ERR,    /*!< Pas d'erreur. */
   STR_EMPTY_ERR, /*!< Erreur: Objet vide ou non initialisé. */

   NB_STR_ERR     /*!< Nombre total de constantes d'erreur. */
}
Str_err_e;

Enumération:
    STR_NO_ERR      Pas d'erreur.
    STR_EMPTY_ERR   Erreur: Objet vide ou non initialisé.
    NB_STR_ERR      Nombre total de constantes d'erreur.

III-D. Exemple complet en C

/**
 * \file main.c
 * \brief Programme de tests.
 * \author Franck.H
 * \version 0.1
 * \date 6 septembre 2007
 *
 * Programme de test pour l'objet de gestion des chaînes de caractères Str_t.
 *
 */
#include <stdio.h>
#include <stdlib.h>
#include <string.h>


/**
 * \struct Str_t
 * \brief Objet chaîne de caractères.
 *
 * Str_t est un petit objet de gestion de chaînes de caractères. 
 * La chaîne se termine obligatoirement par un zéro de fin et l'objet 
 * connait la taille de chaîne contient !
 */
typedef struct
{
   char * sz;  /*!< Chaîne avec  caractère null de fin de chaîne. */
   size_t len; /*!< Taille de la chaîne sz sans compter le zéro de fin. */
}
Str_t;


/**
 * \enum Str_err_e
 * \brief Constantes d'erreurs.
 *
 * Str_err_e est une série de constantes prédéfinie pour diverses futures 
 * fonctions de l'objet Str_t.
 */
typedef enum
{
   STR_NO_ERR,    /*!< Pas d'erreur. */
   STR_EMPTY_ERR, /*!< Erreur: Objet vide ou non initialisé. */

   NB_STR_ERR     /*!< Nombre total de constantes d'erreur. */
}
Str_err_e;


/**
 * \fn static Str_err_e str_destroy (Str_t ** self)
 * \brief Fonction de destruction de l'objet Str_t.
 *
 * \param self Adresse de ll'objet Str_t à détruire.
 * \return STR_NO_ERR si aucune erreur, STR_EMPTY_ERR sinon.
 */
static Str_err_e str_destroy (Str_t ** self)
{
   Str_err_e err = STR_EMPTY_ERR;

   if (self != NULL && *self != NULL)
   {
      free (* self);
      *self = NULL;

      err = STR_NO_ERR;
   }

   return err;
}


/**
 * \fn static Str_t * str_new (const char * sz)
 * \brief Fonction de création d'une nouvelle instance d'un objet Str_t.
 *
 * \param sz Chaîne à stocker dans l'objet Str_t, ne peut être NULL.
 * \return Instance nouvelle allouée d'un objet de type Str_t ou NULL.
 */
static Str_t * str_new (const char * sz)
{
   Str_t * self = NULL;

   if (sz != NULL && strlen (sz) > 0)
   {
      self = malloc (sizeof (* self));

      if (self != NULL)
      {
         self->len = strlen (sz);
         self->sz = malloc (self->len + 1);

         if (self->sz != NULL)
         {
            strcpy (self->sz, sz);
         }
         else
         {
            str_destroy (& self);
         }
      }
   }

   return self;
}


/**
 * \fn int main (void)
 * \brief Entrée du programme.
 *
 * \return EXIT_SUCCESS - Arrêt normal du programme.
 */
int main (void)
{
   Str_err_e err;
   Str_t * my_str = str_new ("Ma chaine de caracteres !");

   if (my_str != NULL)
   {
      printf ("%s\n", my_str->sz);
      printf ("Taille de la chaine : %d\n", my_str->len);

      err = str_destroy (& my_str);

      if (! err)
      {
         printf ("L'objet a ete libere correctement !\n");
      }
   }

   return EXIT_SUCCESS;
}

III-E. Exemple complet en C++

#ifndef CPLAYER_H_
#define CPLAYER_H_

/*!
 * \file CPlayer.h
 * \brief Lecteur de musique de base
 * \author hiko-seijuro
 * \version 0.1
 */
#include <string>
#include <list>

/*! \namespace player
 * 
 * espace de nommage regroupant les outils composants 
 * un lecteur audio
 */
namespace player
{
  /*! \class CPlayer
   * \brief classe representant le lecteur
   *
   *  La classe gere la lecture d'une liste de morceaux
   */
  class CPlayer
  {
  private:
    std::list<string> m_listSongs; /*!< Liste des morceaux*/
    std::list<string>::iterator m_currentSong; /*!< Morceau courant */
                                                

  public:
    /*!
     *  \brief Constructeur
     *
     *  Constructeur de la classe CPlayer
     *
     *  \param listSongs : liste initial des morceaux
     */
    CPlayer(std::list<string> listSongs);

    /*!
     *  \brief Destructeur
     *
     *  Destructeur de la classe CPlayer
     */
    virtual ~CPlayer();

  public:
    /*!
     *  \brief Ajout d'un morceau
     *
     *  Methode qui permet d'ajouter un morceau a liste de
     *  lecture
     *
     *  \param strSong : le morceau a ajouter
     *  \return true si morceau deja present dans la liste,
     *  false sinon
     */
    bool add(std::string strSong);

    /*!
     *  \brief Morceau suivant
     *
     *  Passage au morceau suivant
     */
    void next();

    /*!
     *  \brief Morceau precedent
     *
     *  Passage au morceau precedent
     */
    void previous();

    /*!
     *  \brief Lecture 
     *
     *  Lance la lecture de la liste
     */
    void play();

    /*!
     *  \brief Arret
     *
     *  Arrete la lecture
     */
    void stop();
  };
};

#endif

IV. Avant d'aller plus loin...

sudo aptitude install graphviz doxygen doxygen-gui

Dont  graphviz permet la génération de graphiques (entre autres, des graphiques de dépendances... oui oui, il fait également ça ce merveilleux programme !) et doxygen-gui est l'interface graphique (doxywizard) !

V. Configuration de Doxygen avec Doxywizard

franhec@lucie:~$ doxywizard

V-A. Onglet "Project"

1. Le nom de votre projet.
2. La version du projet.
3. Le répertoire du code source dont il faut générer la documentation.
4. Si cette case est cochée, Doxygen ira fouiller également dans les sous-répertoires à la recherche de codes sources.
5. Emplacement où il faut générer la documentation. Un répertoire html est créé par défaut par Doxygen à l'emplacement spécifié où la documentation y sera placée.

V-B. Onglet "Mode"

V-C. Onglet "Output"

1. Page sans zone de navigation, un peu à la manière de ce tutoriel si ont veut.
2. Page HTML avec une zone de navigation en arbre (vue hiérarchique) comme vous avez pu en voir dans les exemples de génération précédents.
3. Documentation au forma HTML compilé. C'est en fait le format des fichiers d'aide de Windows.
4. Cette option supplémentaire permet d'ajouter une zone de recherche, pratique pour de très grosses documentations mais, pour que ce module fonctionne, il faut que PHP soit installé sur le serveur qui héberge, par exemple pour une version en ligne.

V-D. Onglet "Diagrams"

1. Créé un graphique montrant les relations directes et indirectes de chaque classes documentées. Cette option désactive automatiquement la génération de diagrammes intégrée à Doxygen (l'option nommée "Use built-in classes diagram generator").
2. Créé un graphique pour les classes (et structures en ce qui concerne le C) montrant les relations avec les classes de bases ainsi que les relations avec d'autres structures/classes (ex: une structure A qui possède une variable membre du type d'une structure B).
3. Créé un graphique montrant les dépendances entre les différents fichiers documentés. Cette option ne fonctionne qu'avec la génération au format HTML et RTF !
4. Créé un graphique pour chaque fichier d'en-tête documenté montrant les fichiers documentés qu'inclut directement ou indirectement chaque fichier. Un sorte de graphique de dépendances entre chaque fichiers et les fichiers inclus.
5. Créé un graphique représentant la hiérarchie d'une classe, tout en incluant les dénominations textuelles. Supporté uniquement avec le format HTML !
6. Créé un graphique pour chaque fonction, montrant les fonctions que la fonction appelle directement ou indirectement. Cette option n'est utilisable que si vous cochez la case "Include cross-referenced source code in the output" dans le deuxième onglet !

V-E. Valider les options et les enregistrer

VI. Configuration avancée

Chaque nom d'option dans les options avancées de Doxygen correspond en réalité aux options telles qu'elles sont écrites dans le fichier de configuration généré par le programme !

VI-A. Onglet "Project"

• USE_WINDOWS_ENCODING : Permet de forcer l'encodage des caractères par celui utilisé par Windows si la case est cochée, sinon c'est un encodage de type Unix/Linux qui est utilisé.
• BRIEF_MEMBER_DESC : Permet d'afficher ou non la description courte dans la liste des fonctions/énumérations/structures/classes/etc... Liste qui se trouve en haut de page donc avant la partie détaillée de la documentation !
• REPEAT_BRIEF : Permet d'afficher ou non la description courte dans la partie détaillée de la documentation. Cette option et la précédente sont conjointement liées car si vous désactivez ces deux options, la description courte sera tout de même affichée dans la section détaillée de la documentation !
• DETAILS_AT_TOP : Permet d'afficher la description détaillée du fichier en haut de la page si cette option est cochée.

• C
• C++

VI-B. Onglet "Build"

• EXTRACT_PRIVATE (C++ et autre langages orientés objet) : Permet de faire afficher la documentation des fonctions/méthodes et autres membres ayant le qualificateur private.
• EXTRACT_STATIC : Permet de faire afficher la documentation des fonctions/structures/énumérations/etc... ayant le qualificateur static.
• SORT_MEMBER_DOCS : Si elle est cochée, cette option permet de trier les descriptions détaillées par ordre alphabétique sinon, l'ordre est celui de leur déclaration dans le code source.

• C
• C++

Cocher l'option EXTRACT_ALL à le même effet qu'activer l'option "All entities" dans les options de l'assistant de configuration, sauf en ce qui concerne le style du tri !

VI-C. Onglet "HTML"

VI-D. Onglet "Dot"

• UML_LOOK : Permet de générer des diagrammes dans le style UML.
• DOT_IMAGE_FORMAT : Permet de choisir entre trois formats d'images différents soit png, jpg et gif.
• DOT_PATH : Cette option peut s'avérer utile lorsque vous avez un problème de détection du module de génération de graphiques et diagrammes. Cela peut arriver lorsque ce programme n'est pas référencé dans la variable PATH, il faut donc spécifier le chemin dans ce champ !
• MAX_DOT_GRAPH_WIDTH et MAX_DOT_GRAPH_HEIGHT : Permet de changer la taille maximale d'un graphe, respectivement la largeur et la hauteur.
• MAX_DOT_GRAPH_DEPTH : Permet de régler la profondeur maximum d'un graphe.
• DOT_TRANSPARENT : Permet de rendre le fond des images transparent, ca peut être très utile lorsqu'on personnalise l'aspect général de la documentation !

VII. Conclusion

VIII. Rappels des liens

•  Page d'accueil du site officiel
•  La FAQ
•  Page principale du manuel en ligne
•  Créer des listes dans les documentations
•  Liste de toutes les balises
•  Description de toutes les options

IX. Remerciements