Doxygen : Contrôle Anti-Dopage Positif
Total Page：16
File Type：pdf, Size：1020Kb
DEVELOPPEMENT DOXYGEN : CONTRÔLE ANTI-DOPAGE POSITIF Doxygen : contrôle anti-dopage positif Après les virus informatiques1, la vache folle, les e-mails piégés2, l’affaire Miss France3, les têtes de poulets panées4, les disques durs qui crashent5 et la publication des bugs de Windows, une autre menace inquiète les autorités : les documentations automatisées de projets informatiques. Après la Hollande, les premiers cas de dopage ont été signalés en France. Aux sources du problème blanches sur des problèmes pourtant triviaux, mais rendus difficiles par la seule absence de De très nombreux programmeurs souffrent de ne documentation technique d’un programme. D’un jamais avoir appris les règles de base en matière autre côté, c’est aussi la raison pour laquelle la de lisibilité ou de présentation des fichiers plupart des développeurs justifient leurs salaires sources. En effet, certains professeurs oublient exagérés, mais en fait très justifiés : après tout, parfois d’enseigner à leurs étudiants l’importance eux seuls savent maintenir un code illisible ! des commentaires et négligent la documentation technique d’un Car tout le problème tient en cela : la majorité du projet informa- travail d’un développeur consiste justement à tique. Il en maintenir du code déjà écrit, qu’il en ait été le résulte des développeur initial ou non. Or, pour ce faire, le programmes développeur a besoin de connaître la structure, le difficiles à fonctionnement, l’organisation interne du maintenir. programme pour pouvoir le modifier avec efficacité, d’où le besoin d’une documentation Certes, il s’agit technique aisément consultable et simple bien d’une d’accès. souffrance que de passer la Pour répondre à ce besoin d’information naturel, semaine, le certaines sociétés informatiques renommées week-end et comme Microsoft ont lancé de vastes projets de des nuits documentation au service des développeurs, autant internes qu’externes. Chez Microsoft, donc, la principale source d’informations est le Microsoft Developer Network6 (MSDN.) De son côté, Sun a mis en place le Sun Developer Connection7, les systèmes UNIX continuent à fournir des « man pages » accessibles depuis la ligne de commande. Des sociétés plus modestes maintiennent une base Les documentations dopées et générées via Doxygen rendent les projets beaucoup plus faciles d’information à jour grâce à des à maintenir et menacent ainsi l’emploi dans l’informatique. En effet, de très nombreux équipes rédactionnelles programmeurs gardant jalousement – voire en otage – les secrets de fabrication de leur code complètes. voient leur ouvrage clairement exposé aux spécialistes tout comme aux néophytes. Au lieu d’un brouhaha inintelligible, les développeurs responsables de la maintenance du code se retrouvent Pour être efficace, la face à une documentation de référence claire et compréhensible. Face à ce gain spectaculaire documentation technique d’un de productivité, les développeurs ont les pires difficultés à justifier leurs heures supplémentaires programme en cours de ou les retards de livraison. développement se doit avant (Images de documentation reproduites avec autorisation, © 2001 Rivage Games, http://www.rivagegames.com.) tout d’être à jour. Ainsi, un Dernière mise à jour le lundi 14 mai 2001 à 22:31. 1 DEVELOPPEMENT DOXYGEN : CONTRÔLE ANTI-DOPAGE POSITIF certain nombre d’organisations ont ainsi décidé Doxygen est un programme développé de lancer le développement d’outils de initialement sous Linux par Dimitri van Heesch12 documentation automatiques8 permettant – à sous licence GNU GPL, en faisant un logiciel partir des seuls fichiers sources – de générer des « libre » et gratuit. Les plus perspicaces auront documents clairs et efficaces, réduisant ainsi les noté que cette licence est contaminente : tout coûts de création et de maintenance des projet basé sur les fichiers sources13 de Doxygen documentations. hérite obligatoirement de la licence GNU GPL, le forçant à rester « libre » (quel paradoxe !) Ce- Cependant, ces systèmes payants ou limités à pendant, l’utilisation de Doxygen pour générer la un unique langage de programmation9 ont connu documentation d’un projet propriétaire et dont les un succès limité, de sorte que l’industrie fichiers sources ne suivent pas ladite licence informatique n’avait pas à s’inquiéter du reste absolument possible. chômage. En effet, les responsables informatiques, conscients des répercussions Graphviz économiques de milliers d’informaticiens mis au chômage, pouvaient prétexter un coût prohibitif, Doxygen un manque de flexibilité ou autres subterfuges peut pour justifier le maintient, voire l’augmentation de utiliser leurs équipes. l’outil dot.exe Or, le problème vient justement de là : Doxygen fourni met à disposition des développeurs une chaîne avec de production de la documentation entièrement Graphviz gratuite d’un projet informatique écrit en que vous C/C++/Java/IDL. La documentation peut être pouvez générée au choix aux formats HTML, DHTML, trouver sur son site web officiel CHM, RTF et Latex et ce sans aucune http://www.research.att.com/sw/tools/graphviz/. Il modification du code source. Bien entendu, les suffit d’installer le programme par exemple dans développeurs peuvent encore améliorer la qualité le dossier . des documents générés en mettant en forme C:\Program Files\graphviz quelques commentaires standards au sein de Notons que Graphviz est un programme « open leurs fichiers sources, de sorte à rendre les source » gratuit. informations ainsi publiées encore plus pertinentes et efficaces. Installer Microsoft HTML Help Workshop Installation Pour pouvoir La démarche la plus efficace pour se convaincre générer de l’ampleur du problème est sans doute la mise des en pratique de toute la chaîne de production document Doxygen sur un projet avec lequel on rencontre ations au des difficultés de maintenance. Aussi, nous format verrons ici comment rapidement10 mettre en CHM14, place ce genre de systèmes. Veuillez noter que vous cette expérience n’est décrite ici qu’à des fins devez d’illustration et ne doit surtout pas être reproduite installer à des fins pédagogiques ou commerciales, sous Microsoft peine perturber la vie des développeurs11. Afin de HTML Help Workshop que vous pouvez limiter les répercussions sur l’économie télécharger depuis sa page officielle mondiale, les étapes décrites plus loin se http://msdn.microsoft.com/library/tools/htmlhelp/c limiteront à une installation sous Windows pour hm/hh1start.htm. Installez-le par exemple dans le une utilisation avec un projet en C++. dossier C:\Program Files\HTML Help Workshop. Installer Doxygen Microsoft HTML Help Workshop est un pro- Téléchargez Doxygen depuis son site web officiel gramme gratuit. (Malgré cette gratuité, aucun lien http://www.doxygen.org, puis dézippez de collaboration entre Microsoft et Doxygen n’a programme dans le dossier C:\Program pu être établi à ce jour.) Files\doxygen-x.y.z où vous remplacerez « x.y.z » par le numéro de version du programme (actuellement 1.2.7.) Dernière mise à jour le lundi 14 mai 2001 à 22:31. 2 DEVELOPPEMENT DOXYGEN : CONTRÔLE ANTI-DOPAGE POSITIF Mise en route donc préférable de créer un fichier batch dans le dossier de votre projet C++ à documenter : Tout comme pour l’installation, nous @echo off nous limiterons ici à rem DODOCS.BAT la mise en route de echo Building documentation... Doxygen dans le cas d’un projet C++ sous rem Create the documentation’s HTML files Windows dans ce "C:\Program Files\doxygen-1.2.7\bin\doxygen" soucis de limiter les effets néfastes15 de rem Convert HTML files into CHM file cette démonstration "C:\Program Files\HTML Help Workshop\hhc" sur le devenir de docs_doxy\html\index.hhp l’Humanité. rem Display the CHM file docs_doxy\html\index.chm Générer un fichier de configuration Générer la documentation Doxygen est un Il ne vous reste plus qu’à lancer le fichier batch logiciel très flexible, dodocs.bat pour générer, puis afficher la permettant de documentation. générer des documentations en Aller plus loin divers formats. Aussi, cet utilitaire Comme nous venons de le voir, Doxygen permet nécessite l’emploi de générer une documentation à partir d’un projet d’un fichier de non préparé à cet effet. La documentation ainsi configuration texte obtenue permet de naviguer à travers les divers pour déterminer les fichiers sources, explorer la hiérarchie et options activées. apprécier les diagrammes de collaboration. Ceci est déjà en soi insupportable. Pour générer un fichier de Mais Doxygen permet aussi d’aller beaucoup configuration par plus loin, grâce à l’utilisation de nombreuses défaut, veuillez taper balises à insérer dans les commentaires des "C:\Program fichiers sources. Ainsi, les développeurs atteints 16 Files\doxygen- du « syndrome Monsieur Propre » se verront 1.2.7\bin\doxygen" -g depuis la ligne de pris d’une envie irrépressible de commenter commande dans le dossier de votre projet C++ à chaque classe, chaque variable, chaque documenter. Cette commande produit le fichier paramètre, agrémentant leur documentation de configuration Doxyfile que nous d’exemples commentés, d’images et de modifierons avec les valeurs suivantes : références aux documents externes. OUTPUT_DIRECTORY = docs_doxy Les formats de sortie générés par Doxygen ne se INPUT = . limitent pas au HTML. Certes, le HTML peut FILE_PATTERN = *.cpp *.h *.inl *.c servir comme ici à la construction d’une version RECURSIVE = YES CHM, mais il peut aussi être destiné à une EXCLUDE = docs_doxy consultation depuis un site web, en liaison ou EXAMPLE_PATH = docs_doxy/examples IMAGE_PATH