Outils de génération de documentation
Transcript of Outils de génération de documentation
Outils de génération de documentation
Ecole ENVOL 2010
F. LangrognetLaboratoire de Mathématiques de Besançon
F. Langrognet () Génération de documentation ENVOL 2010 1 / 48
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéBalisesExemplesDiagrammes et graphesPersonnalisation des sorties
4 Pour aller plus loin ...
F. Langrognet () Génération de documentation ENVOL 2010 2 / 48
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéBalisesExemplesDiagrammes et graphesPersonnalisation des sorties
4 Pour aller plus loin ...
F. Langrognet () Génération de documentation ENVOL 2010 3 / 48
Introduction
Introduction
ObjectifGénérer automatiquement (ou
presque...) une documentation
technique
Pour qui ?Tous les développeurs
Y compris moi !
Historique1995-1997 : 1ers outils de
génération :◮ javadoc, ROBODoc (1995)
◮ Doxygen (1997)
F. Langrognet () Génération de documentation ENVOL 2010 4 / 48
Caractéristiques - Fonctionnalités
CaractéristiquesFormats d’entrée
Code source (texte)
Binaire
Formats de sortie
HTML
Latex
ps
XML
man pages
RTF
DocBook
Autres fonctionnalités
Diagrammes (classes, appels, . . . )
Possibilité d’étendre à d’autreslangages
Personnalisation des sorties
. . .
F. Langrognet () Génération de documentation ENVOL 2010 8 / 48
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéBalisesExemplesDiagrammes et graphesPersonnalisation des sorties
4 Pour aller plus loin ...
F. Langrognet () Génération de documentation ENVOL 2010 9 / 48
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéBalisesExemplesDiagrammes et graphesPersonnalisation des sorties
4 Pour aller plus loin ...
F. Langrognet () Génération de documentation ENVOL 2010 10 / 48
Sur quels types de fichiers ?
Fichier binaireDocumentation générée à partir des binairesExemple : classDoc pour java
Fichier sourceDocumentation générée à partir du code source
Grammaire du langage
Balises spécifiques
On peut donc générer des documentations sans balise spécifique
F. Langrognet () Génération de documentation ENVOL 2010 11 / 48
Exemple sans balise
Date.h Documentation générée (html)
F. Langrognet () Génération de documentation ENVOL 2010 12 / 48
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéBalisesExemplesDiagrammes et graphesPersonnalisation des sorties
4 Pour aller plus loin ...
F. Langrognet () Génération de documentation ENVOL 2010 13 / 48
Pour quelles sorties ?
Quelles informations ?
Prototype de fonctions
Classes
Graphes d’appels
Diagrammes (de classses, de collaboration, . . .)
Liens vers les fichiers sources
. . .
Format des fichiers de sortie
Différents formats (en fonction des possibilités de l’outil) :html, pdf, latex, ps, XML, . . .
Personnalisation possible des sorties
F. Langrognet () Génération de documentation ENVOL 2010 14 / 48
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéBalisesExemplesDiagrammes et graphesPersonnalisation des sorties
4 Pour aller plus loin ...
F. Langrognet () Génération de documentation ENVOL 2010 15 / 48
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéBalisesExemplesDiagrammes et graphesPersonnalisation des sorties
4 Pour aller plus loin ...
F. Langrognet () Génération de documentation ENVOL 2010 16 / 48
Doxygen - Fiche d’identité
Auteur : Dimitri Van Heesch
1re version : 1997
OS : BSD, Linux, Mac OS, Unix, Windows
Entrée : code source
Sorties : (HTML, LATEX, Man Pages, RTF, XML, Qt Help Project, PDF, PS, . . . )
Nombreuses possibilités de personnalisation
Documentation KDE
F. Langrognet () Génération de documentation ENVOL 2010 17 / 48
Pour quels langages ?
Langages
+ Possibilités d’extension pour d’autres langages non natifs
F. Langrognet () Génération de documentation ENVOL 2010 18 / 48
Comment utilise t-on Doxygen (1) ?
En ligne de commande
Directement :user$ doxygen *.h *.cpp
Via une fichier de configuration :
◮ user$ doxygen -g my_config.txt◮ user$ kate my_config.txt
◮ user$ doxygen my_config.txt
F. Langrognet () Génération de documentation ENVOL 2010 19 / 48
Comment utilise t-on Doxygen (2) ?
GUIExemple : DoxyWizard pour configurer et lancer doxygen
ConfigurationFormats de sorties Types de sorties
F. Langrognet () Génération de documentation ENVOL 2010 20 / 48
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéBalisesExemplesDiagrammes et graphesPersonnalisation des sorties
4 Pour aller plus loin ...
F. Langrognet () Génération de documentation ENVOL 2010 21 / 48
Balises
Balises à l’intérieur des commentairesLes balises sont incluses dans les commentaires interprétables par Doxygen
En C/C++ :
Style C avec avec deux */*** Documentation pour doxygen*/
Style C avec avec un !/* !* Documentation pour doxygen*/
Style C++ avec avec trois /////// Documentation pour doxygen///
Style C++ avec avec un !// !// !Documentation pour doxygen// !
F. Langrognet () Génération de documentation ENVOL 2010 22 / 48
Balises
Balises
\fileDescription d’un fichier source ou d’en-tête
\briefDescription courte (peut être complétée par un lien vers
la description détaillée)
\authorAuteur(s)
\versionVersion
\dateDate
\paramDescription de paramètre(s) d’une fonction (/méthode)
\returnDescription de la valeur retournée
\bugDescription d’un bug
\deprecatedDescription d’une partie de code obsolète
\classDescription d’une classe
F. Langrognet () Génération de documentation ENVOL 2010 23 / 48
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéBalisesExemplesDiagrammes et graphesPersonnalisation des sorties
4 Pour aller plus loin ...
F. Langrognet () Génération de documentation ENVOL 2010 24 / 48
Doxygen - Exemples
Informations sur les fichiers d’en-tête
F. Langrognet () Génération de documentation ENVOL 2010 25 / 48
Informations d’en-tête (1)
Sans balise doxygen
Avec balises d’en-têtedoxygen
F. Langrognet () Génération de documentation ENVOL 2010 26 / 48
Informations d’en-tête (2)Balises d’en-tête
F. Langrognet () Génération de documentation ENVOL 2010 27 / 48
Doxygen - Exemples
Description courte / détaillée
F. Langrognet () Génération de documentation ENVOL 2010 28 / 48
Description courte / détaillée (1)Description courte / détaillée
On peut avoir :
une description courte (\brief)
une description détaillée (sans balise)
F. Langrognet () Génération de documentation ENVOL 2010 29 / 48
Description courte / détaillée (2)Description courte / détaillée
On peut aussi générer automatiquement la description courte à partir de la description détaillée(option JAVADOC_AUTOBRIEF à YES).
La description courte s’arrête au 1er point trouvé dans la description détaillée.
F. Langrognet () Génération de documentation ENVOL 2010 30 / 48
Doxygen - Exemples
Description d’une méthode / fonction
F. Langrognet () Génération de documentation ENVOL 2010 31 / 48
Description d’une méthode / fonction (1)Description d’une méthode
Utilsation de \param et \return.
F. Langrognet () Génération de documentation ENVOL 2010 32 / 48
Description d’une méthode / fonction (2)
Balises pour une méthode / fonction
F. Langrognet () Génération de documentation ENVOL 2010 33 / 48
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéBalisesExemplesDiagrammes et graphesPersonnalisation des sorties
4 Pour aller plus loin ...
F. Langrognet () Génération de documentation ENVOL 2010 34 / 48
Diagrammes de classes (1)
Fonctionnement par défautHiérarchie de classes
F. Langrognet () Génération de documentation ENVOL 2010 35 / 48
Diagrammes de classes (2)Personnalisation
Avec le logiciel graphviz (et l’option HAVE_DOT=YES)
Hiérarchie de classes
Diagramme de collaboration
F. Langrognet () Génération de documentation ENVOL 2010 36 / 48
Diagrammes de classes (3)
Autre exemple
F. Langrognet () Génération de documentation ENVOL 2010 37 / 48
Graphes d’appels
Graphes d’appels (et l’option CALL_GRAPH=YES)
Graphes d’appelants (et l’option CALLER_GRAPH=YES)
F. Langrognet () Génération de documentation ENVOL 2010 38 / 48
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéBalisesExemplesDiagrammes et graphesPersonnalisation des sorties
4 Pour aller plus loin ...
F. Langrognet () Génération de documentation ENVOL 2010 39 / 48
Personnalisation des sorties (1)Sortie HTML
Exemple de personnalisation :
user$ doxygen -w html header.html footer.html customdoxygen.css
Feuille de style
En-tête
Pied de page
F. Langrognet () Génération de documentation ENVOL 2010 40 / 48
Personnalisation (2)Disposition des sorties
Création d’un fichier layout :user$ doxygen -l
Edition du fichier DoxygenLayout :user$ kate DoxygenLayout.xml
Edition du fichier de configuration(LAYOUT_FILE = DoxygenLayout.xml) :
user$ kate config.xml
Execution de doxygen :user$ doxygen config.txt
DoxygenLayout.xml
F. Langrognet () Génération de documentation ENVOL 2010 41 / 48
PLAN
1 Introduction
2 Comment ça marche ?Sur quels types de fichiers ?Pour quelles sorties ?
3 Un exemple détaillé : DoxygenFiche d’identitéBalisesExemplesDiagrammes et graphesPersonnalisation des sorties
4 Pour aller plus loin ...
F. Langrognet () Génération de documentation ENVOL 2010 42 / 48
Quel outil de génération de documentation choisir ?
Quel langage ?
F. Langrognet () Génération de documentation ENVOL 2010 43 / 48
Quel outil de génération de documentation choisir ?
Quel langage ? ... suite
F. Langrognet () Génération de documentation ENVOL 2010 44 / 48
Quel outil de génération de documentation choisir ?
Quel OS ?
F. Langrognet () Génération de documentation ENVOL 2010 45 / 48
Quel outil de génération de documentation choisir ?
Format de sortie
F. Langrognet () Génération de documentation ENVOL 2010 46 / 48
RéférencesQuelques références
Comparaison des outils de génération de documentation :en.wikipedia.org/wiki/Comparison_of_documentation_generators
Doxygen :
◮ Doxygen (officiel) :www.stack.nl/ dimitri/doxygen/
◮ Manuel d’utilisation Doxygen :www.stack.nl/ dimitri/doxygen/manual.html
◮ Wikipedia :fr.wikipedia.org/wiki/Doxygen
◮ Initialtion à Doxygen pour le C++ :franckh.developpez.com/tutoriels/outils/doxygen/
javadoc
◮ officiel :download.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html
◮ Wikipedia :fr.wikipedia.org/wiki/Javadoc
F. Langrognet () Génération de documentation ENVOL 2010 47 / 48