Doxygen Méthodologie de production d’applications

Doxygen
Ce TP est une initiation à doxygen. Doxygen est un logiciel qui permet de générer la
documentation d’un code à partir du code lui-même. Des commentaires spéciaux
permettent de générer plus finement cette documentation. La documentation générée par
doxygen est destinée à d’autres développeurs, et non aux utilisateurs finaux du logiciel.

Exercice 0 Mise en place

Récupérez les sources de LAPIN depuis le dépôt https://gitlab-lepuy.iut-
clermont.uca.fr/prod2a/lapin.
Clonez-le et créez votre propre branche ou faites un « fork » de ce projet.
Récupérez sur le cours en ligne le fichier doc.zip et décompressez-le. L’objectif est de
reproduire cette aide en ligne (accessible en ouvrant le fichier html\index.html)
directement dans le code source de LAPIN à l’aide de commandes doxygen.

Exercice 1 Fichier de configuration de doxygen.

Doxygen est un logiciel permettant de réaliser la documentation d’un code source à partir de
commentaires du code. Doxygen se paramètre par un fichier de configuration pour chaque projet.

1.1 Utilisation de Doxywizard

Exécutez le logiciel Doxywizard (Démarrer / Doxygen / Doxywizard)
Ce logiciel est un assistant de création du fichier de configuration pour doxygen
ère
1 étape : spécifier le répertoire de travail. Cliquez sur le bouton Select et choisissez le
répertoire des sources de LAPIN. Ce répertoire sera alors le point de départ des chemins
relatifs que nous donnerons à doxygen.
Cliquez sur l’onglet « Wizard » pour créer un premier fichier de configuration par défaut.
Nous allons créer un fichier permettant de configurer doxygen pour créer un fichier d’aide au
format HTML.
Paramètres du projet
Entrez dans le premier écran le nom du projet (LAPIN - Logiciel d'Apprentissage Pour
Imagerie Numérique) et sa version (2.0).
Spécifiez le répertoire du code source, c'est-à-dire ‘./’ relativement au répertoire de
travail. Si le projet LAPIN contient des sous-répertoires dans lesquels des fichiers
sources doivent être analysé, alors vous devez cocher la case ‘scan recursively’.
Entrez ‘.\doc’ dans la zone « Destination directory » pour que le fichier d’aide soit
créé dans le sous répertoire « doc » du répertoire des sources.
Paramètres du mode d’extraction
Choisissez ‘all entities’ pour documenter toutes les parties du code même celles qui
ne sont pas explicitement documentées dans le code.
Cochez la case ‘include cross-referenced source code in the output’ qui permettra
d’avoir dans l’aide en ligne le code source muni de lien hypertexte vers la
documentation de chaque objet/classe.

2020-2021 Adélaïde et Benjamin ALBOUY-KISSI 1

Doxygen Méthodologie de production d’applications

Vérifiez que la case ‘Optimize for C++ output’ est sélectionnée

2020-2021 Adélaïde et Benjamin ALBOUY-KISSI 2

Doxygen Méthodologie de production d’applications

Paramètres du format de sortie

Ne cochez que la case HTML et sélectionnez ‘with frames and a navigation tree’
Assurez-vous d’avoir coché ‘With search function’.
Paramètres des diagrammes
Sélectionnez ‘use dot tool from the GraphViz package’ et cochez tous les diagrammes
possibles sauf ‘Call graphs’ et ‘Called by graphs’. Cette option spécifie que doxygen
utilisera un logiciel tiers (GraphViz, installé sur les machines) pour générer les
graphiques concernant le code.

Une fois les paramètres entrés, enregistrez le fichier de configuration (File / Save) et lancez
la génération de l’aide en cliquant sur ‘Run doxygen’ dans l’onglet ‘Run’

Une fois la génération terminée, vous pouvez voir le résultat en cliquant sur ‘Show HTML
Output’ ou en ouvrant le fichier ./doc/html/index.html dans un navigateur web.

1.2 Configuration avancée de doxygen

Certains problèmes ont pu apparaitre à la génération. Notamment, l’insertion d’images
échoue et le texte automatiquement généré par doxygen est en anglais. Il faut alors faire quelques
réglages fins en cliquant sur l’onglet ‘Expert’.

Paramètres du projet :
Dans OUTPUT_LANGUAGE, spécifiez ‘French’.
Paramètre de génération :
Cochez EXTRACT_PRIVATE et EXTRACT_STATIC afin que les membres privés et
statiques soient inclus dans la documentation.
Paramètres d’entrée :
Vous avez la possibilité d’exclure des fichiers et/ou répertoires sources de la génération.
Par exemple, dans le cas d’un projet réalisé avec Qt, les répertoires GeneratedFiles et
intermédiaires x64 devraient être exclus de façon à ne pas documenter du code source
spécifique à Qt. Dans la liste EXCLUDE, rajoutez ces deux répertoires.
Lorsque des images sont à insérer dans le fichier de documentation, le(s) répertoire(s) de
stockage des images doi(ven)t être spécifié(s) à doxygen. Dans le cas de LAPIN, des images
sont insérées dans la page principale de l’aide, et se trouvent dans le répertoire des
sources. Aouter donc le répertoire courant ‘.’ A la liste IMAGE_PATH.
Paramètres de sortie HTML
De nombreux paramètres permettent de personnaliser l’affichage de l’aide en HTML. Par
exemple, vous pouvez spécifier un en-tête et un pied de page personnalisé pour chacune
de vos pages HTML, ou changer la feuille de style par défaut de doxygen. Pour ce TP, on
se contentera de cocher l’option HTML_DYNAMIC_SECTION, permettant de rendre
l’affichage de certaines sections des pages HTML interactif.

1.3 Doxygen et Git

Vous avez créé un nouveau fichier pour votre projet : le fichier de configuration de doxygen.
Ce fichier doit donc être versionné avec tout votre projet. Ajoutez donc ce fichier à votre dépôt Git. En
revanche, le répertoire doc a été généré automatiquement, il ne doit donc pas être versionné ! Ajoutez
ce répertoire à la liste des fichiers ignorés du dépôt Git.

2020-2021 Adélaïde et Benjamin ALBOUY-KISSI 3

Doxygen Méthodologie de production d’applications

Exercice 2 Définition des commentaires dans le code.

L’aide en ligne qui a été générée ne contient que des informations générées automatiquement.
Les paramètres et fonctionnalités des fonctions/classes ne sont donc pas indiqués. L’objet de cet
exercice est d’ajouter au code les commentaires adéquats pour qu’ils soient pris en compte par
doxygen.

Pour déterminer quels commentaires sont de la documentation, doxygen repère les lignes de
commentaires qui commencent par //! ou par /*! :

//! Ce commentaire sera interprété par doxygen

// Celui-ci, non.

/*! Celui-ci sera également interprété par doxygen

* et peut être écrit sur plusieurs lignes
*/

/* Celui-là est un simple commentaire de code

* ignoré par doxygen */

Pour mettre en forme la documentation, doxygen repère dans ces blocs des commandes qui
commencent par le caractère ‘\’. Par exemple la commande \file permet d’ajouter un commentaire
portant sur tout le fichier. La liste de ces commandes est disponible dans l’aide en ligne de doxygen
(Démarrer / Doxygen / Doxygen documentation → section « special commands »)

2.1 Documentation des fichiers

Chaque fichier peut avoir une documentation qui lui est propre. Pour cela, il suffit d’ajouter en
début de chaque fichier un commentaire de documentation.

Pour chaque fichier de code source de LAPIN (fichiers .h et .cpp) :

Ajoutez un bloc de commentaire de documentation de la forme :

//////////////////////////////////////////////////////////////////////
//! \file Nom_du_fichier
//!
//! \brief Présentation briève du fichier
//!
//! Présentation détaillée du fichier
//!
//! \date date de modification du fichier
//! \version version du fichier
//////////////////////////////////////////////////////////////////////

Compilez votre fichier d’aide et testez-le pour voir vos modifications.

2020-2021 Adélaïde et Benjamin ALBOUY-KISSI 4

Doxygen Méthodologie de production d’applications

2.2 Documentation des classes

Chaque classe peut avoir une documentation qui lui est propre. Pour cela, il suffit d’ajouter
avant chaque déclaration de classe un commentaire de documentation.

Pour chaque classe déclarée dans le code source de LAPIN (classes LAPIN, QLAPINImage et
QLAPINThreshold) :
Avant la déclaration de la classe, ajoutez un bloc de commentaire de documentation de
la forme :

//////////////////////////////////////////////////////////////////////
//! \class nom de la classe
//!
//! \brief Description briève de la classe
//!
//! \author Auteur principal de cette classe
//! \date Date de création de la classe
//! \version Version de la classe
//!
//! Description détaillée de la classe
//////////////////////////////////////////////////////////////////////

Compilez votre fichier d’aide et testez-le pour voir vos modifications.

2.3 Documentation des membres

Chaque donnée et fonction membre peut avoir une documentation qui lui est propre. Pour
cela, il suffit d’ajouter avant chaque définition de fonction un commentaire de documentation.

Pour chaque donnée et fonction membre déclarée dans le code source de LAPIN (fichiers .h) :

Avant le membre, ajoutez un bloc de commentaire de documentation pour spécifier

brièvement le rôle du membre.

Avant chaque fonction membre définie dans le code source de LAPIN (fichiers .cpp) :

Ajoutez un bloc de commentaire de documentation de la forme :

//////////////////////////////////////////////////////////////////////
//! \author Nom de l’auteur de la fonction
//! \date Date de dernière modification
//!
//! \param NomParamètre Description du paramètre (à faire pour chacun)
//!
//! \return (éventuellement) Description de la valeur de sortie
//! \throw (éventuellement) Description des exceptions possible
//!
//! Description détaillée de la fonction
//////////////////////////////////////////////////////////////////////

Compilez votre fichier d’aide et testez-le pour voir vos modifications.

2020-2021 Adélaïde et Benjamin ALBOUY-KISSI 5

Doxygen Méthodologie de production d’applications

2.4 Documentation sur la page principale

Doxygen permet d’écrire directement dans le code source du logiciel la page principale du
fichier d’aide. Il suffit pour cela d’utiliser la commande \mainpage. Vous pouvez également ajouter
des images à l’aide de la commande \image et des sections à l’aide de \section. En vous aidant de
l’aide de doxygen, essayer de reproduire la page principale de l’aide de LAPIN en commandes doxygen
dans le fichier main.cpp.

2020-2021 Adélaïde et Benjamin ALBOUY-KISSI 6