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.

Image non disponible

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

Image non disponible

V-B. Mode

Image non disponible

V-C. Output

La documentation générée par Doxygen peut être de type HTML, LaTeX, Man (aide Unix), RTF ou XML.

Image non disponible

V-D. Diagrams

Image non disponible

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.

Image non disponible

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)
Image non disponible
  • un en haut
Image non disponible

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.

Image non disponible

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.

Image non disponible

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.

Image non disponible

VIII. Commentaires du code source

Les commentaires du code source font la documentation générée. Les commentaires extraits sont les suivants :

 
Sélectionnez
/**
* commentaires
*/
 
Sélectionnez
/*!
* commentaires
*/
 
Sélectionnez
/**
commentaires
*/
 
Sélectionnez
///
/// commentaires
///
 
Sélectionnez
//!
//! commentaires
//!
 
Sélectionnez
//////////////////////
/// 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.

 
Sélectionnez
/*! \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 :

 
Sélectionnez
/** 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 :

 
Sélectionnez
@author, @deprecated, @exception, @param, @return,
@see, @serial, @serialData, @serialField, @since,
@throws, @version

X. 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.