I. Introduction▲
La pérennité d'un projet de développement dépend pour beaucoup de la qualité de sa documentation technique à l'usage des développeurs qui auront en charge de maintenir l'application et de la faire évoluer. Cette documentation peut s'avérer fastidieuse à écrire.
C'est pourquoi il existe des outils qui extraient directement de l'information du code source pour produire une documentation. Ce code source peut être commenté avec des tags spécifiques.
À l'exemple de Javadoc qui produit de la documentation à partir du code source, l'outil Doxygen extrait l'information à partir du code source et bien plus encore…
II. Télécharger Doxygen▲
Ce document se base sur la version 1.3.8.
Site officiel : http://www.doxygen.org
Cet outil est Open Source et sous licence GNU GPL. Il est disponible sous les plateformes :
- Linux (Debian, RedHat, Suse…) ;
- Mac OS ;
- Windows.
III. GUI▲
Une interface graphique permet de configurer aisément Doxygen et de lancer l'analyse de vos sources pour en produire une documentation.
IV. Configuration▲
Avant de lancer l'analyse de vos sources, il faut configurer Doxygen. Il existe deux modes de configuration :
- wizard : configuration de base ;
- expert : configuration avancée pour les experts.
Vous pouvez laisser les paramètres par défaut.
Vous pouvez enregistrer votre configuration pour la recharger lors d'une analyse ultérieure.
V. Configuration Wizard▲
La configuration de base est constituée de quatre onglets :
- project : informations générales sur votre projet ;
- mode : le mode d'analyse ;
- output : le type de documentation à générer ;
- diagrams : les diagrammes à générer.
V-A. Project▲
V-B. Mode▲
V-C. Output▲
La documentation générée par Doxygen peut être de type HTML, LaTeX, Man (aide Unix), RTF ou XML.
V-D. Diagrams▲
VI. Analyse▲
Le lancement de l'analyse de vos codes sources se fait en cliquant sur « Start ».
Le détail des opérations effectuées par Doxygen apparait dans la zone de texte. Puis s'affiche :
« *** Doxygen has finished »
lorsque la génération de la documentation a été réalisée.
VII. Rendu HTML▲
La documentation HTML produite par Doxygen se trouve dans le sous-répertoire html/ du répertoire de sortie spécifié dans la configuration.
VII-A. Menus de navigation▲
Il existe deux menus de navigation :
- un à gauche dans une frame (si l'option adéquate est sélectionnée dans la configuration)
- un en haut
VII-B. Optimisation Java▲
La documentation HTML des projets Java comporte les chapitres suivants :
| Chapitres | Description |
| Main Page | La page de garde du projet avec son nom et le numéro de version |
| Packages | Liste des packages avec une courte description de chacun d'eux |
| Class Hierarchy | La hiérarchie des classes |
| Class List | La liste alphabétique des classes et interfaces avec une courte description |
| File List | La liste des fichiers avec une courte description et un lien vers leur code source colorisé et lignes numérotées |
| Class Members | Liste alphabétique des méthodes et variables du projet en correspondance avec leur classe |
VII-C. Code source▲
Le code source des classes documentées est intégré à la documentation. Des liens hypertextes sur chaque méthode, classe et attribut documentés pointent vers leur documentation respective. Les lignes de code sont numérotées. Doxygen intègre la coloration syntaxique.
VII-D. Index des entités▲
Le chapitre « Class Members » liste toutes les méthodes et tous les attributs du projet par ordre alphabétique et par catégorie et pointe vers leur classe respective.
VII-E. Diagrammes▲
La documentation de chaque classe est accompagnée d'un diagramme d'héritage et d'interface. Chaque classe du diagramme comprend un lien hypertexte vers sa documentation.
VIII. Commentaires du code source▲
Les commentaires du code source font la documentation générée. Les commentaires extraits sont les suivants :
/**
* commentaires
*//*!
* commentaires
*//**
commentaires
*////
/// commentaires
/////!
//! commentaires
//!//////////////////////
/// commentaires
//////////////////////Les courtes descriptions (à distinguer des descriptions longues normales) affichées sur les pages Packages, Class Hierarchy, Class List et File List sont introduites par le mot-clé \brief.
/*! \brief Voici une courte description
* sur plusieurs lignes.
*
* Et ici la description longue normale.
*/Si le paramètre de configuration JAVADOC_AUTOBRIEF est mis à YES, alors le mot clé \brief est inutile :
/** Voici une courte description
* terminée par un point.
*
* Et ici la description longue normale.
*/IX. Épilogue▲
Les commentaires Javadoc traditionnels sont interprétés par Doxygen.
Rappel des tags Javadoc les plus courants :
@author, @deprecated, @exception, @param, @return,
@see, @serial, @serialData, @serialField, @since,
@throws, @versionX. Historique▲
22 août 2004 : mise à jour Rendu HTML (22 diapos).
21 août 2004 : création du document (18 diapos).
Agissez sur la qualité de ce document en envoyant vos critiques et suggestions à l'auteur.
Pour toute question technique, se reporter au forum Java de Developpez.com.
© Tous droits réservés. La copie, modification et/ou distribution, de tout ou partie de celui-ci, par quelque moyen que ce soit, est soumise à l'obtention préalable de l'autorisation de l'auteur.
XI. Note et remerciement du gabarisateur▲
Cet article a été mis au gabarit de developpez.com. Voici le lien vers le PDF d'origine : doxygen.pdf.
Le gabarisateur remercie Philippe DUVAL et Claude LELOUP pour sa correction orthographique.