Documenter un projet avec Doxygen 1.3.8

Hugo ETIEVANT

Documenter un projet avec Doxygen 1.3.8

Télécharger l'outil Doxygen 1.3.8 pour Windows :
Site officiel - Miroir Developpez.com

Visualiser un exemple de documentation générée

- Titre : Documenter un projet avec Doxygen 1.3.8

- Auteur : Hugo ETIEVANT

- Parution : 21 août 2004

- Licence : Copyright ® 2004 Hugo ETIEVANT. Aucune reproduction, même partielle, ne peut être faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu'à trois ans de prison et jusqu'à 300 000 € de dommages et intérêts.

Sommaire

- I. Introduction

- II. Télécharger Doxygen

- III. GUI

- IV. Configuration

- V. Configuration Wizard

- V-A. Project

- V-B. Mode

- V-C. Output

- V-D. Diagrams

- VI. Analyse

- VII. Rendu HTML

- VII-A. Menus de navigation

- VII-B. Optimisation Java

- VII-C. Code source

- VII-D. Index des entités

- VII-E. Diagrammes

- VIII. Commentaires du code source

- IX. Épilogue

- X. Historique

- XI. Note et remerciement du gabarisateur

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, @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.