Mouviciel

Création d'applications pour Mac OS X

Les coulisses d'un développeur Mac

Bien documenter son code avec Doxygen et Xcode

Publié le samedi 7 février 2009, 3 commentaires

Dans cet article, je vous propose de rationaliser la documentation de votre code grâce à Doxygen. Cette documentation sera produite automatiquement par Xcode et apparaîtra comme DOC SET dans le menu Documentation de Xcode.

Un petit état des lieux

Il m'est arrivé d'écrire du code dans un état d'excitation créative tel que tout ce dont j'avais envie, c'était de voir fonctionner la réalisation de mes idées. Je voulais savoir le plus vite possible si ce que j'imaginais allait marcher comme je le voulais. C'est dans ces moments-là qu'on ne voit pas l'heure tourner et qu'on n'entend pas l'estomac demander une pause. Bien entendu, seul le code était important. Les variables s'appelaient a, b, ou c, parfois i, j, k. Les commentaires seraient pour plus tard, lorsque le premier jet serait au point.

Il m'est aussi arrivé de reprendre ce code quelques mois, voire quelques années plus tard... Inutile de vous faire un dessin : je ne comprenais plus rien au plat de spaghetti que j'avais écrit. Il serait plus facile de tout reprendre de zéro que d'essayer de retrouver ce que tout ce fatras voulait dire.

Avec l'age, j'arrive beaucoup plus facilement à me dominer dans ces situations et à commenter mon code le plus clairement possible. En écrivant les commentaires, je pense à mon lectorat: ce ne sont pas d'autres développeurs, c'est moi dans six mois. Mais même ainsi, il m'arrive d'avoir des difficultés à m'y retrouver. J'y vois plusieurs raisons :

Doxygen pour y voir plus clair ?

Mauvaise nouvelle, Doxygen ne résoud pas tout ces problèmes.

Mais il y a une bonne nouvelle, Doxygen est capable d'extraire de la documentation pour un code sans aucun commentaire ! Il fait l'inventaire de toutes les classes, de toutes les variables et méthodes dans chaque classe, des dépendances entre tout cela, il trace des graphes de dépendances entre les fichiers et des graphes d'héritage entre les classes. J'en ai peut-être oublié.

Voyons cela sur un exemple simple. Nous allons d'abord installer Doxygen, puis créer un projet Cocoa qui servira de support

Téléchargez Doxygen pour Mac et installez-le par exemple dans votre dossier ~/Applications. Nous ne nous servirons pas de l'application Mac OS X, seulement de l'application doxygen en ligne de commande qui y est incluse. Pour cela, j'ai ajouté les lignes suivantes dans mon fichier .bash_profile :

#
# Ajout du chemin pour Doxygen
#
export PATH=${PATH}:${HOME}/Applications/Doxygen.app/Contents/Resources

Éditez le fichier avec l'application Terminal, ensuite fermez la fenêtre qui vous a servi à éditer puis ouvrez-en une autre. Cette procédure permet que les modifications soient prises en compte.

Maintenant, ouvrez Xcode et créez un nouveau projet d'application Cocoa, nommez-le par exemple DoxygenTutorial. Dans son état initial, ce projet contient le strict minimum pour qu'une application Cocoa puisse être compilée et lancée sans erreur. Il y a principalement deux fichiers : main.m et MainMenu.xib.

Avec l'application Terminal, rendez-vous dans le dossier du projet DoxygenTutorial. La première opération, à réaliser une fois pour toutes, est de créer la configuration Doxygen pour le projet. Il s'agit d'un fichier nommé Doxyfile. La commande suivante permet de le créer (dans la fenêtre du Terminal, dans le dossier du projet) :

doxygen -g

Nous allons changer un tout petit peu la configuration. Ouvrez le fichier Doxyfile avec n'importe quel éditeur et modifiez les points suivants (le texte modifié est en gras, les ellipses indiquent les portions du fichier à ne pas changer) :

...
PROJECT_NAME           = DoxygenTutorial
...
OUTPUT_LANGUAGE        = French
...
EXTRACT_ALL            = YES
...
EXTRACT_PRIVATE        = YES
...
EXTRACT_STATIC         = YES
...
EXTRACT_LOCAL_METHODS  = YES
...
GENERATE_LATEX         = NO
...
HAVE_DOT               = YES
...

Ensuite, pour créer la documentation du projet, la commande est simplement la suivante :

doxygen

La documentation est créée dans un dossier nommé html. Ouvrez-là avec la commande :

open html/index.html

Vous devriez obtenir quelque chose comme cela :

Amorce de documentation

Si vous cliquez sur l'onglet Fichiers (pas celui ci-dessus, celui que vous avez généré chez vous) vous devriez obtenir la liste de tous les fichiers sources du projet, à savoir main.m. Vous devriez aussi avoir accès à tous les éléments que ce fichier déclare, à savoir la fonction main() avec la liste de ses arguments et un graphe de dépendances des fichiers inclus :

Documentation de main.m

Souvenez-vous que nous avons obtenu cela sans rien ajouter au code initial ! voyons maintenant quelques petits exemples de ce qu'on peut obtenir en documentant vraiment.

La documentation bien comprise

Documenter avec Doxygen signifie ajouter des commentaires spéciaux dans le code que l'outil reconnaitra et utilisera pour élaborer la documentation. Ces commentaires spéciaux sont introduits avec le signe de commentaire traditionnel auquel on ajoute une barre supplémentaire : ///. Dans ces sections de commentaires Doxygen, la documentation est écrite à l'aide de mots-clés qui servent à identifier la structure des cmmentaires.

Le premier exemple que je vous propose consiste à écrire une petite introduction destinée à la page de présentation de la documentation. Ajoutez les commentaires suivants dans le fichier main.m :

//
//  main.m
//  DoxygenTutorial
//
//  Created by mouviciel on 25/01/09.
//  Copyright Mouviciel 2009. All rights reserved.
//

/// \file
/// \brief Point d'entrée de l'application

/// \mainpage
///
/// Cette application a pour vocation d'illustrer l'utilisation de
/// Doxygen dans un projet Xcode/Cocoa.
///
/// \section Présentation
///
/// D'abord, quelques tags d'usage général sont introduits, tels que
/// \\file, \\brief, \\mainpage et \\section.

#import 

int main(int argc, char *argv[])
{
    return NSApplicationMain(argc,  (const char **) argv);
}

Relancez la commande doxygen, puis ouvrez à nouveau la page principale de la documentation et observez. Faites aussi un petit tour dans l'onglet Fichiers. Je vous laisse le soin d'ajouter la documentation que vous souhaitez.

Le deuxième exemple que je vous propose est la documentation de la fonction main(), ses arguments, ses valeurs de retour et son contenu. Voici une suggestion :

/// \brief Fonction principale de l'application
///
/// La fonction main() est invoquée au lancement de l'application.
/// Ses arguments permettent d'accéder aux paramètres de la
/// ligne de commande.
///
/// \param argc
///     Le nombre de paramètres présents sur la ligne de commande.
///     Il y a toujours au moins un paramètre.
/// \param argv
///     Liste des paramètres présents sur la ligne de commande.
///     Le premier paramètre est la commande elle-même.
///
/// \return
///     Le code de retour de la fonction, transmis au processus parent
///     sous forme de status de retour (accessible en shell via la
///     variable $?).
///
/// \section Implémentation
///
/// La fonction main() réalise les opérations suivantes:

int main(int argc, char *argv[])
{
    /// - Lancement de l'application Cocoa.
    return NSApplicationMain(argc,  (const char **) argv);
}

Après avoir lancé à nouveau doxygen, je vous invite à consulter la page de la documentation consacrée au fichier main.m. Remarquez par exemple l'hyperlien créé automatiquement sur chaque référence à la fonction main(). Ici c'est trivial et à peu près sans intérêt, mais dans des codes plus gros ce genre de référence entre les fichiers ou entre les classes devient très utile pour se retrouver.

Pour aller plus loin, je vous invite à consulter le manuel de Doxygen.

Intégrer Doxygen dans Xcode

L'intégration de Doxygen dans Xcode se passe à deux niveaux. D'une part, il est utile de pouvoir produire la documentation d'un projet depuis Xcode, soit en créant une target spécifique, soit en l'intégrant directement dans la compilation du projet. D'autre part, il est possible de produire une documentation accessible directement depuis le menu Help — Documentation de Xcode.

Dans ce qui suit, je vous montre comment intégrer l'étape de génération de documentation à la compilation. Il s'agit simplement d'exécuter un script shell à la fin de la construction de la cible. Voici la démarche.

Dans la fenêtre Xcode du projet DoxygenTutorial, dans la colonne Groups & Files, déployez la rubrique Targets ainsi que la cible DoxygenTutorial à l'intérieur. Cette cible contient les éléments Copy Bundle Resources, Compile Sources et Link Binary With Libraries. Nous allons ajouter un quatrième élément Run Script. Pour cela, sélectionnez la cible DoxygenTutorial puis activez l'élément de menu Project — New Build Phase — New Run Script Build Phase. Une fenêtre s'ouvre, dans laquelle vous allez écrire le script shell suivant :

# Localisation de doxygen et dot
DOXYGEN_PATH=${HOME}/Applications/Doxygen.app/Contents/Resources
PATH=${DOXYGEN_PATH}:${PATH}
export PATH

# Génération de la documentation
doxygen || exit 1

Voilà c'est tout ! Maintenant, chaque fois que vous cliquerez sur un des petits marteaux Build ou Build and Go, la documentation de votre logiciel sera produite.

Mais l'étape la plus intéressante est à venir : vous pouvez intégrer la documentation de votre propre logiciel dans le navigateur de documentation de Xcode. Bien sûr la présentation sera un peu différente, mais vous aurez toutes les facilités du navigateur telle la recherche rapide. Pour y parvenir, il suffit de modifier le fichier Doxyfile de configuration de Doxygen ainsi que le petit script que nous venons d'écrire.

D'abord, voici les modifications à apporter à Doxyfile :

...
GENERATE_DOCSET        = YES 
...
DOCSET_FEEDNAME        = "Documentation de DoxygenTutorial"
...
DOCSET_BUNDLE_ID       = fr.exemple.doxygentutorial
...

Ces modifications indiquent à Doxygen qu'il doit produire des fichiers d'index supplémentaires ainsi qu'un Makefile qui sera utilisé pour placer la documentation au bon endroit avec le bon format.

Ensuite, voici les modifications à apporter au script que nous venons d'écrire pour produire la documentation:

# Localisation de doxygen et dot
DOXYGEN_PATH=${HOME}/Applications/Doxygen.app/Contents/Resources
PATH=${DOXYGEN_PATH}:${PATH}
export PATH

# Génération de la documentation
doxygen || exit 1

# Génération du Documentation Set
make -C html install || exit 1

# Ouverture du Documentation Set dans Xcode
DOCSET_PATH=Library/Developer/Shared/Documentation/DocSets
open $HOME/$DOCSET_PATH/fr.exemple.doxygentutorial.docset || exit 1

Maintenant, cliquez sur le petit marteau de Build, et observez le résultat. Bravo ! Vous venez de documenter votre code et d'installer cette documentation aux côtés de la documentation Apple !

À partir d'ici, je vous laisse potasser la documentation de Doxygen et vous approprier cet outil très utile.

Commentaires

pauline

Le lundi 30 mai 2011 à 09:22

bjr,
quel est le code a generer avec doxygen pour avoir une barre de recherche????

Rei Vilo

Le samedi 9 juin 2012 à 23:39

Merci pour cette excellente introduction à Doxygen.

L'essayer c'est l'adopter !

hi

Le mardi 26 mars 2013 à 00:02

Comment ouvrir automatiquement le fichier de code source (sous xcode en l'occurrence) à partir de la doc générée sour Doxygen ?

Ajoutez un commentaire

Les commentaires sont destinés à répondre en public à l'article visé et à ses commentaires déjà publiés. C'est pourquoi seul un pseudonyme vous est demandé ici. Si vous souhaitez échanger avec moi en privé, merci de me laisser un message via le menu contact en haut de la page.

Archive

Rubriques

Abonnement