1
Download Support du cours
Transcript
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é : Doxygen Fiche d’identité Balises Exemples Diagrammes et graphes Personnalisation 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é : Doxygen Fiche d’identité Balises Exemples Diagrammes et graphes Personnalisation des sorties 4 Pour aller plus loin ... F. Langrognet () Génération de documentation ENVOL 2010 3 / 49 Introduction Introduction Objectif Générer automatiquement (ou presque...) une documentation technique Pour qui ? Tous les développeurs Y compris moi ! Historique 1995-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 Exemples NetBeans (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éristiques Formats d’entrée Code source (texte) Binaire Fonctionnalités ’avancées’ Formats de sortie Diagrammes (classes, appels, . . . ) HTML Possibilité d’étendre à d’autres langages PDF Latex Personnalisation des sorties ps ... XML man pages RTF DocBook 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é : Doxygen Fiche d’identité Balises Exemples Diagrammes et graphes Personnalisation 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é : Doxygen Fiche d’identité Balises Exemples Diagrammes et graphes Personnalisation 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 binaires Exemple : classDoc pour java à partir des .class ou .jar Fichier source Documentation 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 F. Langrognet Documentation générée (html) () 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é : Doxygen Fiche d’identité Balises Exemples Diagrammes et graphes Personnalisation 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é : Doxygen Fiche d’identité Balises Exemples Diagrammes et graphes Personnalisation 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é : Doxygen Fiche d’identité Balises Exemples Diagrammes et graphes Personnalisation 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) ? GUI Exemple : DoxyWizard pour configurer et lancer doxygen Configuration Formats de sorties F. Langrognet () Génération de documentation Types de sorties ENVOL 2010 21 / 49 PLAN 1 Introduction 2 Comment ça marche ? Sur quels types de fichiers ? Pour quelles sorties ? 3 Un exemple détaillé : Doxygen Fiche d’identité Balises Exemples Diagrammes et graphes Personnalisation des sorties 4 Pour aller plus loin ... F. Langrognet () Génération de documentation ENVOL 2010 22 / 49 Balises Balises à l’intérieur des commentaires Les 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 trois / /// /// Documentation pour doxygen /// Style C avec avec un ! /* ! * Documentation pour doxygen */ Style C++ avec avec un ! // ! // !Documentation pour doxygen // ! F. Langrognet () Génération de documentation ENVOL 2010 23 / 49 Balises Balises \file Description d’un fichier source ou d’en-tête \brief Description courte (peut être complétée par un lien vers la description détaillée) Description de paramètre(s) d’une fonction (/méthode) \return Description de la valeur retournée \bug \author Description d’un bug Auteur(s) \deprecated \version Description d’une partie de code obsolète Version \class \date Description d’une classe Date F. Langrognet \param () 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é : Doxygen Fiche d’identité Balises Exemples Diagrammes et graphes Personnalisation 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 F. Langrognet () Avec balises d’en-tête doxygen 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é : Doxygen Fiche d’identité Balises Exemples Diagrammes et graphes Personnalisation 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éfaut Hié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é : Doxygen Fiche d’identité Balises Exemples Diagrammes et graphes Personnalisation 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 DoxygenLayout.xml 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 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é : Doxygen Fiche d’identité Balises Exemples Diagrammes et graphes Personnalisation 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érences Quelques références Comparaison des outils de génération de documentation : en.wikipedia.org/wiki/Comparison_of_documentation_generators Doxygen : ◮ Doxygen (officiel) : ◮ Manuel d’utilisation Doxygen : ◮ Wikipedia : ◮ Initialtion à Doxygen pour le C++ : www.stack.nl/ dimitri/doxygen/ www.stack.nl/ dimitri/doxygen/manual.html fr.wikipedia.org/wiki/Doxygen franckh.developpez.com/tutoriels/outils/doxygen/ javadoc ◮ officiel : ◮ Wikipedia : download.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html 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
