mer, 18/11/2009 - 16:59 par Dom
Type:
Sujet:
Tutoriel: Documenter un code avec Doxygen
Introduction à Doxygen
A l'instar de Javadoc, Doxygen est un lgociel libre de documentation de code possédant des capacités de génération de documentation à partir du code source d'un programme. Pour cela il tient compte de la syntaxe et de la structure du langage du programme ainsi que des commentaires associés à condition que ceux-ci soient écrit dans un format adapté. C'est cette manière de commenter que nous allons étudier dans cet article.
La génération de documentation peut être faite à partir de code dans les langages suivants: C, C++, Java, Objective C, Python, IDL, VHDL et dans une certaine mesure PHP, C# et D. Le résultat final est une documentation complète générée en HTML (compressé ou non), LaTeX, RTF, PostScript, PDF avec hyperliens, et XML.
Les logiciels nécessaires à cette génération sont:
- Doxygen, pour la génération de documentation au format HTML, LaTex, PostScript et XML...
Installation sous windows:
sudo apt-get install doxygen doxygen-gui - Graphviz, pour la génération de graphes (graphes d'appel, de dépendances, ...).
Installation sous windows:
télécharger la dernière version et puis lancer graphviz-xxx.msi
Installation sous Linux:
sudo apt-get install graphviz - MikTex pour la génération de documentation au format pdf avec hyperliens.
Installation sous windows:
télécharger la dernière version et puis lancer basic-miktex-xxx.exe
- HTML WorkShop, pour la génération de documentation au format HTML compressé.
Installation sous windows:
télécharger la dernière version et puis lancer htmlhelp.exe
Commenter son code avec Doxygen
Généralités dans les commentaires
Afin de différencier dans un fichier les commentaires à l'intention de Doxygen de ceux qui ne sont pas à prendre en compte, Doxygen possède sa propre norme de documentation, ou plutôt ses propres normes puiqu'il vous permet le choix entre l'une ou l'autre de ses différentes formes suivantes:
/**
* Ceci est un commentaire multiligne compris par Doxygen.
* C'est cette convention que nous utiliserons par la suite....
*/
/*!
* ... Remarquez toutefois que suivant votre propre goût,
* vous pouvez utilisez celle-ci.....
*/
//!
//! ... ou celle-là. L'important comme souligné dans l'article précédent de ce dossier,
//! c'est de concerver la même convention tout au long de votre programme....
//!
///
/// ... Toutes ces formes de commentaires multilignes
/// peuvent toutefois être utilisez de façon monoligne...
///
int iValeur = 5; /** ... et ce même après une ligne de code. */
/* En revanche, les formes de commentaires conventionnelles */
// ne seront pas pris en compte par Doxygen.
Listes des attributs
Afin de préciser et de donner du sens aux commentaires, chaque information essentielle dispose d'une balise pour en préciser la nature. Une balise peut s'écrire \balise ou @balise. Par la suite, nous utiliserons la convention \balise.
Voici la liste des balises Doxygen les plus courantes (par ordre alphabétique):
\a Utiliser pour faire ressortir un paramètre dans sa description.
ex: /** ...les coordonnées \a x et \a y du point.... */
donne
...les coordonnées x et y du point....
\author {liste d'auteur}
Utiliser pour indiquer l'auteur du fichier ou de la fonction, structure ou de la chose décrite.
ex: /** \author Miroslav */
\b Utiliser pour mettre en gras un mot dans une description; équivalent à mot en HTML.
ex: /** ...il est \b important que.... */ donne ...il est important que....
\brief Utiliser pour créer un résumé de description.
ex: /**
* \brief Ici le résumé de la description...
*...qui peut prendre plusieurs lignes (mais rester bref)
*
* Ici la description complète...
*/
\bug Utiliser pour indiquer un bug dans une fonction ou un morceau de programme.
ex: /** \bug La probabilité calculée dépasse parfois 1. */
\class [] []
Utiliser pour décrire une classe. Le premier paramètre est obligatoire, les suivants optionnels.
Attention toutefois à ce que les paramètres soit corrects, la casse est prise en compte.
ex: /** \class Voiture voiture.h "inc/voiture.h" */
class Voiture { };
\date Utiliser pour indiquer la date de création de la partie commentée.
ex: /** \date 7 juin 1954 */
\def Utiliser pour indiquer un commentaire pour une macro #define.
ex: /** \def MAX(x,y) */
\e Utiliser pour emphasier un mot dans une phrase. Equivalent à la balise HTML em.
ex: /** ....ceci constitue un \e vraiment bon exemple.... */
donne
...ceci constitue un vraiment bon exemple...
\enum
ex: /** \enum COULEUR */
\file
L'attribut doit être exact et fourni avec l'extension.
ex: /** \file mon_fichier.c */
\fn Utiliser pour introduire la description d'une fonction.
Peut-être omis si la description est placée immédiatement
sous la déclaration de la fonction et sans saut de ligne.
ex: /** \fn Cette fonction calcul le..... */
\namespace
L'attribut doit être exact.
ex: /** \namespace maths */
\param {description}
Utiliser pour lister et décrire les paramètres d'une fonction.
Le nom doit être exact et la description optionnelle peut-être multiligne.
Peut être suivi de [in], [out] ou [in,ou] pour indiquer si les paramètres sont input-output.
ex: /** Cette fonction copie les \a n premiers caractères d'une chaîne dans une autre.
* \param[out] dst la chaîne de destination
* \param[in] src la chaîne à copier
* \param n le nombre de caractère à copier
*/
char *strncpy (char *dst, const char *src, size_t n);
\return {description}
Utiliser pour décrire le paramètre renvoyé par une fonction. La description peut-être multiligne.
ex: il suffit d'ajouter à l'exemple précédent la ligne:
* \return renvoit la chaîne de caractère contenu dans src.
\struct [] []
Utiliser pour décrire une structure. Le premier paramètre est obligatoire, les suivants optionnels.
Attention toutefois à ce que les paramètres soit corrects, la casse est prise en compte.
ex: /** \struct Pixel pixel.h "inc/pixel.h" */
struct Pixel{ };
\todo {description}
Utiliser pour indiquer ce qu'il reste à faire. La description peut être multiligne.
ex: /**
* \todo Finir l'implémentation des accesseurs de la classe...
* ...et encore détails nécessitant plusieurs lignes
*/
\typedef Utiliser pour introduire la description d'un typedef.
ex: /** \typedef Voiture: la classe voiture */
\union [] []
Utiliser pour décrire une union. Le premier paramètre est obligatoire, les suivants optionnels.
Attention toutefois à ce que les paramètres soit corrects, la casse est prise en compte.
ex: /** \union Couleurs couleurs.h "inc/couleurs.h" */
union Couleurs{ };
\version Utiliser pour définir la version d'un fichier.
ex: /** \version 1.0beta */
\@ \& \\ \< \~ \# \% ...
Utiliser pour insérer le caractère correspondant dans une description.
ex: /** Applique aux attributs \#1 et \#2 parsé en XML.
*{cf fichier \~.tmp; en cas de problème contacter l'@auteur} */
donne
Applique aux attributs #1 et #2 parsé en XML.
{cf fichier ~.tmp en cas de problème contacter l'@uteur}
Le lecteur est évidement invité à consulter la liste complète de toutes les balises Doxygen pour documenter au mieux son projet.
Commenter un fichier
Voici un exemple de commentaire d'en-tête de fichier s'appliquant au fichier module_modeleVoiture.c . L'ordre des balises n'a pas d'importance.
/**
* \file module_modeleVoiture.c
* \author Miroslav
* \version 1.0
* \date 12 Novembre 2009
* \brief Définit les modèles de voiture et leur particularités.
*
* \details Cette classe surcharge les accesseurs standards du module_voiture pour
* convenir aux spécificités des différents modèles possibles.
*/
La documentation résultante après analyse simple (pas de graphe d'appel ni de dépendance) par Doxygen:
Commenter une fonction ou une méthode
Voici un exemple de commentaire de fonction ou de méthode. L'ordre des balises n'a pas d'importance mais les balises \param ne peuvent être omises.
/**
* \brief Calcule la distance entre deux points
* \details La distance entre les \a point1 et \a point2 est calculée par l'intermédiaire
* des coordonnées des points. (cf #Point)
* \param point1 Point 1 pour le calcul de distance.
* \param point2 Point 2 pour le calcul de distance.
* \return Un \e float représentant la distance calculée.
*/
La documentation résultante après analyse simple (pas de graphe d'appel ni de dépendance) par Doxygen:
Commenter une structure ou une union
Voici un exemple de commentaire de structure ou d'union. L'ordre des balises n'a pas d'importance. Comme vous le remarquerez, nous introduisons ici l'opération < permettant d'insérer un commentaire pour un membre de la structure ou de l'union.
/**
* \brief Couleur possible pour un Point.
* \details La table de correspondance de couleurs est disponible en modification par les accesseurs.
*/
* \brief Couleur possible pour un Point.
* \details La table de correspondance de couleurs est disponible en modification par les accesseurs.
*/
typedef enum
{
COLOR_BLUE, /*!< Couleur bleu (0,0,255) */
COLOR_DARK_RED, /*!< Couleur rouge sombre (64,0,0) */
COLOR_OLIVE /*!< Couleur olive (51,51,0) */
}
Color;
{
COLOR_BLUE, /*!< Couleur bleu (0,0,255) */
COLOR_DARK_RED, /*!< Couleur rouge sombre (64,0,0) */
COLOR_OLIVE /*!< Couleur olive (51,51,0) */
}
Color;
La documentation résultante après analyse simple par Doxygen:
Générer la documentation Doxygen
Doxygen est installé? Votre code est entièrement documenté? Il ne reste plus qu'à générer votre documentation. Pour cela lancer doxywizard.exe depuis windows ou la commande
doxywizard depuis linux.Etape 1: Entrer un chemin vers un répertoire de travail.
Etape 2: Remplir les 4 parties de l'assistant Wizard de Doxygen. Outre le mode Wizard, vous remarquerez que le logiciel propose le mode Expert. L'onglet Run sert à lancer la génération de la documentation une fois que la configuration est correctement effectuée, soit par l'onglet Wizard soit par l'onglet Expert.
Utilisation de l'assistant
Voyons comment remplir les quatres parties de l'onglet Wizard:
Projet:
Cette partie est très simple à remplir et les différentes options ne méritent pas de long commentaire. Elle sert à fournir les informations générales nécessaires à la génération de la documentation.
Project name: Remplir le nom du projet.
Project version: La version du projet.
Source code directory: Le répertoire contenant le code source à analyser et documenter.
Scan recursively: En cochant cette case, l'analyse du répertoire source se fera de façon récursive.
Les sources contenus dans les sous-répertoires seront alors analysée.
Destination directory: Le répertoire dans lequel sera crée la documentation.
Mode:
La partie Mode spécifie les options des sources à analyser ainsi que la méthode d'analyse.
Documented entities only: Seules les entités (fonctions, méthodes, fichiers, structures...) documentées seront analysées et placées dans la documentation résultante.
All Entities: Toutes les entités présentent dans le source seront analysées et documentées. Cette option ne peut pas générer du texte de documentation à votre place mais permet en revanche d'inclure toutes les entités dans les structures avec des liens entre elles pour une relecture plus aisée.
Include cross-referenced: Les fichiers sources seront insérés dans la documentation avec une coloration syntaxique appropriée et des liens vers les documentations précises.
Select programming language to optimize the result for: Ces options spéciales permettent de choisir la présentation de la documentation résultante la mieux adaptées au langage de votre source.
Output:
Cette partie spécifie les options de génération de la documentation, notamment le format de sortie.
- HTML : générer une documentation au format HTML
- Plain HTML : HTML pur
- with frame and navigation tree : Ajoute une navigation facilitée par une présentation arborescente.
- compressed HTML : Format des documentations Windows (.chm)
- with search function : ajoute une barre de recherche dans la documentation.
Attention: ne fonctionne que sur un serveur interprétant le PHP.
- Latex : générer une documentation LaTex
- intermediaire format for :
Propose trois options de sorties au format LaTex adaptées pour un post-traitement de conversion de la documentation au format PDF avec hyperliens, PDF pur ou PostScript.
- Man Pages : générer une documentation au format ManPages: format des documentations Linux.
- RTF : générer une documentation au format RTF (Rich Text Format).
- XML : générer une documentation au format XML.
Diagrams:
Cette partie permet de configurer la création de diagramme dans la documentation.
- no diagrams: Pas de création de diagramme.
- built-in class diagram generator: Créer la documentation par défaut.
- use GraphViz: Permet la création de diagram supplémentaires insérés dans la documentation.
Les diagrammes sont des schémas graphiques représentant des situations données. Les différents diagrammes proposées sont nombreux:
- Créer une représentation des relations directes et indirectes entre les classes.
- Montre les relations d'interdépendance des classes et structures.
(ex: un membre de classe A est du type classe B )
- Créer les diagrammes représentant la hiérarchie des classes.
- Créer les graphes de dépendances des fonctions.
- Créer les graphes des fonctions dont dépendent directement et indirectement les fonctions documentées.
- Créer les graphes d'appel direct et indirect des fonctions.
- Créer les graphes des fonctions appelées directement et indirectement par les fonctions documentées.
Quand toutes les options sont configurées, la génération se lance tout simplement en cliquant sur Run Doxygen dans l'onglet Run.
La struture du dossier de documentation résultante sera la suivante:
Vous trouverez => ici <= un exemple de documentation effectué avec Doxygen. Il s'agit de la traduction effectuée par AxiomCafe de la documentation du noyau ChibiOS v1.0
Utilisation du mode expert
Afin de faciliter l'usage du mode Expert, il convient de compléter entièrement le mode Wizard puis de passer en mode Expert avant d'utiliser le Run. Nous n'allons cependant ici présenter que quelques une des fonctions intéressantes du mode Expert. Nous ne reprendrons de plus que les paramètres supplémentaires par rapport au mode Wizard.
Project :
- DOXYFILE_ENCODING : Permet de forcer l'encodage des fichiers de la documentation Doxygen.
- OUTPUT_LANGUAGE : Permet de choisir la langue de la documentation générée.
- BRIEF_MEMBER_DESC : Permet d'afficher (ou non) la description courte dans la liste des fonctions/structures/fichiers/classes/....
Cette description est placée en début de fichier avant la description détaillée.
- REPEAT_BRIEF : Permet d'afficher (ou non) la description courte en haut de la description détaillée dans les fichiers.
- SHORT_NAME : Permet de générer des noms de fichiers courts pour la documentation.
Certains systèmes d'exploitation ne supportent pas les noms longs.
Build :
- EXTRACT_PRIVATE : Permet d'afficher la documentation pour les fonctions/méthodes/membres ayant le qualificateur private.
- EXTRACT_STATIC : Permet d'afficher la documentation pour les fonctions/méthodes/membres ayant le qualificateur static.
- SHOW_DIRECTORIES : Permet d'afficher la hiérarchie des fichiers sources dans la documentation.
- SORT_BRIEF_DOCS : Permet d'afficher la documentation des fichiers, namespaces et fichiers extraits par ordre alphabétique.
Si non cochée, affiche la documentation par ordre de déclaration dans le code source.
Input :
- INPUT_ENCODING : Force la prise en compte de l'encodage des fichiers sources.
Source Browser :
- INLINE_SOURCES : Permet d'insérer le corps des fonctions/méthodes/structures/... extraites dans la documentation.
Index :
- ALPHABETICAL_ORDER : Permet d'afficher la documentation de toutes entités extraites par alphabétique.
Si non cochée, l'ordre dans la documentation est celle de définition dans les fichiers sources.
HTML :
- HTML_HEADER : Permet de forcer le header des fichiers de la documentation. Si laissé vide, le header par défaut est utilisé.
- HTML_FOOTER : Permet de forcer le footer des fichiers de la documentation. Si laissé vide, le footer par défaut est utilisé.
Dot :
- UML_LOOK : Permet de forcer la génération des diagrammes d'héritage et de dépendance selon la norme UML.
- DOT_IMAGE_FORMAT : Permet de forcer le format d'encodage des images (png, jpeg ou gif).
- DOT_GRAPH_MAX_NODES : Permet de limiter le nombre maximum de noeuds d'un graphe.
Si le nombre de noeud dépasse cette valeur alors le graphe est tronqué.
- MAX_DOT_GRAPH_WIDTH et MAX_DOT_GRAPH_HEIGHT: Permet de limiter la taille des graphes générés.
- MAX_DOT_GRAPH_DEPTH : Permet de limiter la profondeur de génération de noeuds d'un graphe.
Si la profondeur dépasse cette valeur alors le graphe est tronqué.
- DOT_TRANSPARENT : Permet de générer des graphes sur fond transparent.
Attention, cette option ne semble pas supportée sous Windows.
Vous avez aimé ? Offrez-nous le café !
Pas tout compris? Laissez un commentaire ou contactez-nous !
Imprimer
Envoyer
Bug ou erreur ?
