Embed Size (px)
Citation preview
Outils de génération de documentation
Ecole ENVOL 2010
F. Langrognet
Laboratoire de Mathématiques de Besançon
F. Langrognet () Génération de documentation ENVOL 2010 1 / 49
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 / 49
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 / 49
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 / 49
Exemples
Java SDK (javadoc)
F. Langrognet () Génération de documentation ENVOL 2010 5 / 49
ExemplesNetBeans (javadoc)
F. Langrognet () Génération de documentation ENVOL 2010 6 / 49
Exemples
KDE (Doxygen)
F. Langrognet () Génération de documentation ENVOL 2010 7 / 49
Caractéristiques - Fonctionnalités
CaractéristiquesFormats d’entrée
Code source (texte)
Binaire
Formats de sortie
HTML
Latex
ps
XML
man pages
RTF
DocBook
Fonctionnalités ’avancées’
Diagrammes (classes, appels, . . . )
Possibilité d’étendre à d’autreslangages
Personnalisation des sorties
. . .
F. Langrognet () Génération de documentation ENVOL 2010 8 / 49
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 / 49
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 / 49
Sur quels types de fichiers ?Fichier binaire
Documentation générée à partir des binairesExemple : classDoc pour java à partir des .class ou .jar
Fichier sourceDocumentation générée à partir du code source
Grammaire du langage
Balises spécifiques
F. Langrognet () Génération de documentation ENVOL 2010 11 / 49
Sur quels types de fichiers ?
La documentation peut ainsi être générée sans aucun effort(sans balise spécifique)
Un des meilleurs outils Résultat/Effort
Mais ... des commentaires (balises) améliorent la qualité de la documentation
F. Langrognet () Génération de documentation ENVOL 2010 12 / 49
Sur quels types de fichiers ?
La documentation peut ainsi être générée sans aucun effort(sans balise spécifique)
Un des meilleurs outils Résultat/Effort
Mais ... des commentaires (balises) améliorent la qualité de la documentation
F. Langrognet () Génération de documentation ENVOL 2010 12 / 49
Exemple sans balise
Date.h Documentation générée (html)
F. Langrognet () Génération de documentation ENVOL 2010 13 / 49
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 14 / 49
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 15 / 49
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 / 49
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 17 / 49
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
Intégré dans de nombreux outils (KDevelop, cmake, . . . )
Documentation KDE
F. Langrognet () Génération de documentation ENVOL 2010 18 / 49
Pour quels langages ?
Langages
F. Langrognet () Génération de documentation ENVOL 2010 19 / 49
Comment utilise t-on Doxygen (1) ?En ligne de commande
Directement :$ doxygen *.h
Via un fichier de configuration :
$ doxygen -g my_config.txt
$ kate my_config.txt
$ doxygen my_config.txt
F. Langrognet () Génération de documentation ENVOL 2010 20 / 49
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 21 / 49
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 22 / 49
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 23 / 49
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 24 / 49
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 25 / 49
Doxygen - Exemples
Informations sur les fichiers d’en-tête
F. Langrognet () Génération de documentation ENVOL 2010 26 / 49
Informations d’en-tête (1)
Sans balise doxygen
Avec balises d’en-têtedoxygen
F. Langrognet () Génération de documentation ENVOL 2010 27 / 49
Informations d’en-tête (2)Balises d’en-tête
F. Langrognet () Génération de documentation ENVOL 2010 28 / 49
Doxygen - Exemples
Description courte / détaillée
F. Langrognet () Génération de documentation ENVOL 2010 29 / 49
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 30 / 49
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 31 / 49
Doxygen - Exemples
Description d’une méthode / fonction
F. Langrognet () Génération de documentation ENVOL 2010 32 / 49
Description d’une méthode / fonction (1)
Utilsation de \param et \return.
F. Langrognet () Génération de documentation ENVOL 2010 33 / 49
Description d’une méthode / fonction (2)
F. Langrognet () Génération de documentation ENVOL 2010 34 / 49
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 35 / 49
Diagrammes de classes (1)
Fonctionnement par défautHiérarchie de classes
F. Langrognet () Génération de documentation ENVOL 2010 36 / 49
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 37 / 49
Diagrammes de classes (3)Autre exemple
F. Langrognet () Génération de documentation ENVOL 2010 38 / 49
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 39 / 49
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 40 / 49
Personnalisation des sorties (1)Sortie HTML
Exemple de personnalisation :
$ 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 41 / 49
Personnalisation (2)Disposition des sorties
Création d’un fichier layout :$ doxygen -l
Edition du fichier DoxygenLayout :$ kate DoxygenLayout.xml
Edition du fichier de configuration(LAYOUT_FILE = DoxygenLayout.xml) :
$ kate config.txt
Execution de doxygen :$ doxygen config.txt
DoxygenLayout.xml
F. Langrognet () Génération de documentation ENVOL 2010 42 / 49
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 43 / 49
Quel outil de génération de documentation choisir ?
Quel langage ?
F. Langrognet () Génération de documentation ENVOL 2010 44 / 49
Quel outil de génération de documentation choisir ?
Quel langage ? ... suite
F. Langrognet () Génération de documentation ENVOL 2010 45 / 49
Quel outil de génération de documentation choisir ?
Quel OS ?
F. Langrognet () Génération de documentation ENVOL 2010 46 / 49
Quel outil de génération de documentation choisir ?
Format de sortie
F. Langrognet () Génération de documentation ENVOL 2010 47 / 49
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 48 / 49
Outils de génération de documentation
FIN
Merci de votre attention
Florent Langrognet
F. Langrognet () Génération de documentation ENVOL 2010 49 / 49
