Documentation de projets en XML - Cahiers GUTenberg
Contents
1. c est vrai lt code gt qui sont vraies bien que troublantes On remarque que la fermeture du premier commentaire et l ouverture du troi si me commentaire ont disparu lors de l extraction du code XML Par contre le second commentaire est conserv tel quel On remarque aussi que le de crire a t transform en amp eacute pour respecter le codage ASCII standard du fichier XML Ce fragment de code XML pourrait tre rendu comme suit sur papier Documentation de projets en XML 19 La nature des tableaux en C permet d crire des choses comme assert tab i i tab c est vrai qui sont vraies bien que troublantes La documentation compl te est compos e de la documentation extraite du code mais aussi de fichiers de documentation pure qui pourront faire r f rence aux annotations du code source 4 Quelle s DTD Une fois construite la documentation doit tre exploit e de diverses fa ons manuel d utilisation r f rence pour d veloppeurs description des algorithmes utilis s etc Chacune de ces vues de la documentation peut utiliser diff rents m dia aide en ligne documentation papier documentation interactive dans un environnement de d veloppement L outil d extraction de documentation n impose aucune contrainte sur la DTD chacun peut donc utiliser la plus adapt e chacun de ses projets Toutefois le d veloppement d outils ou de feui2. cahiers G U 1 enberg DOCUMENTATION DE PROJETS EN XML Fr d ric BOULANGER Yolaine BOURDA Cahiers GUTenberg n 35 36 2000 p 15 23 lt http cahiers gutenberg eu org fitem id CG_2000___35 36_15_0 gt Association GUTenberg 2000 tous droits r serv s Lacc s aux articles des Cahiers GUTenberg http cahiers gutenberg eu org implique l accord avec les conditions g n rales d utilisation http cahiers gutenberg eu org legal html Toute utilisation commerciale ou impression syst matique est constitutive d une infraction p nale Toute copie ou impression de ce fichier doit contenir la pr sente mention de copyright Cahiers GUTenberg n 35 36 Congr s GUTenberg 2000 Toulouse mai 2000 15 Documentation de projets en XML Fr d ric BOULANGER et Yolaine BOURDA Sup lec Service Informatique Plateau de Moulon 3 rue Joliot Curie F 91192 Gif sur Yvette cedex Frederic Boulanger Yolaine Bourda supelec fr R sum Le manque de documentation de la plupart des logiciels et notamment de ceux d velopp s par nos tudiants nous am ne envisager une approche de la documentation par annotation du code dans les commentaires Nous g n ralisons cette approche afin de pouvoir documenter du code en n importe quel langage et de cr er de la documentation n importe quel format XML est toutefois le format que nous privil gions car ce travail s inscrit dans un projet plus vaste de t
3. qu elle regroupe le code et la documentation dans le m me document C est en effet une condition n cessaire mais h las pas suffisante pour que la documentation soit jour vis vis du code qu elle est cens e documenter Malheureusement ce style de programmation tel qu il existe l heure actuelle avec web et cweb a quelques inconv nients qui expliquent peut tre son manque de succ s Tout d abord avant de pouvoir compiler un programme il faut extraire le code du source web Il faut pour cela disposer des outils associ s au style de programmation Pour viter ce probl me lorsqu on distribue le code source d un programme on peut tre tent de distribuer le code d j extrait du m ta source Dans ce cas on distribue un code illisible ce qui revient interdire l utilisateur potentiel de comprendre comment il fonctionne et m me de l adapter sa plateforme ou ses besoins L approche choisie par D E Knuth tait pertinente l poque laquelle TEX a t cr car les outils de d veloppement n offraient pas ce qu apportait le syst me web et les performances des ordinateurs incitaient ne fournir un compilateur que le strict minimum permettant d obtenir le programme voulu De nos jours les langages de programmation supportent la modularit et dis posent de m canismes puissants de v rification du respect des interfaces Les performances des machines permettent de tol rer
4. qu un compilateur traite plus de lignes de commentaires que de lignes de code Une autre approche de la do cumentation de code est donc possible et nous pensons qu elle peut tre utilis e pour tout type de d veloppement et pas uniquement pour la programmation en C C ou Java 2 Principe Le principe de notre approche de la documentation de code est que ce code doit rester compilable directement sans transformation pr alable Cela permet de distribuer le code source document sans obliger les utilisateurs installer l outil de documentation tout en les faisant b n ficier de cette documentation La cons quence imm diate de ce principe est que la documentation se trouve dans les commentaires Sur ce point nous sommes en retrait par rapport la programmation litt raire puisque nous commentons du code alors que dans un source web on code le commentaire du programme Cet inconv nient nous semble largement com pens par les autres avantages de notre approche Une autre cons quence de ce principe est que la seule chose que l outil de documentation doit conna tre du langage est la fa on d isoler les commentaires Documentation de projets en XML 17 Cela permet donc de construire un outil capable de fonctionner avec plusieurs langages et aussi d utiliser plusieurs langages dans un m me projet D autres outils appliquent le principe d un code source directement utilisable mais ils ne fonctionnent que pour
5. ace d entr e indique comment interpr ter certains caract res Dans notre cas on pourra d cider de coder le O exclusif sous la forme xor par exemple et construire un espace d entr e dans lequel xor s interpr te en 7 Conclusion L approche de la documentation que nous proposons tente de conserver certains bons aspects de la programmation litt raire tout en s appuyant plus fortement sur les m canismes fournis par les langages de programmation actuels Elle per met la distribution du code source document en liminant l tape d extraction du code compilable ce qui lui permet de plus de s appliquer tout langage de programmation dont on sait isoler les commentaires et d utiliser plusieurs langages dans un m me projet En choisissant XML pour structurer la documentation nous souhaitons per mettre des outils de projeter diff rentes vues de cette documentation qui pourront s adresser diff rents publics utilisateurs programmeurs tech niciens de maintenance Chacune de ces vues pourra de plus tre pr sent e sur diff rents m dia manuel papier aide en ligne syst me de maintenance assist e par ordinateur Documentation de projets en XML 23 La mise au point d un syst me de DTDs param trables permettra de structurer la documentation de la mani re la plus appropri e tout en b n ficiant d outils capables de la traiter selon une DTD de base Le support de plusieurs fichiers d
6. ces d entr e et de sortie Nous avons d j vu que lorsqu on crit dans un fichier XML certains caract res litt raux doivent tre traduits un amp doit tre crit amp amp Si on crivait dans un fichier ATRX le m me amp devrait tre crit amp La n cessit de coder certains caract res de fa on particuli re peut tre repr sent e par la notion d espace de sortie Ainsi dans l espace de sortie XML l esperluette se code amp amp et le signe inf rieur strict amp 1t Il faut bien noter qu il s agit de l esperluette et du signe inf rieur strict en tant que symboles pas en tant que caract res En effet une balise XML d bute par le caract re lt qui ne doit pas tre remplac par amp 1t De m me le caract re amp d limite gauche les entit s XML et lorsqu il est utilis pour cela il ne doit pas tre remplac par amp amp La notion d espace de sortie permet notre outil d extraire de la documentation sous d autres formats qu XML il suffirait de coder l espace de sortie IATEX dans notre outil pour qu il permette d crire des documents normaux gt et de cr er des fichiers en divers langages Mais cette notion n est pas suffisante il est aussi n cessaire d indiquer comment interpr ter les caract res du fichier source 22 Fr d ric Boulanger et Yolaine Bourda Nous avons vu dans un exemple que le caract re dans le fichier sourc
7. e tait traduit en amp eacute dans l espace de sortie XML Cette fa on de dire les choses est partiellement fausse c est en effet le symbole e accent aigu qui est cod ainsi en XML Il manque ce qui a permis l outil de reconna tre un e accent aigu dans le caract re du fichier source Ce qu on a lu n est qu un nombre et il faut conna tre le codage du document pour l interpr ter comme un Toutefois l interpr tation du contenu du fichier source ne se limite pas l utilisation d un codage des caract res Reprenons notre exemple du fichier de tests pour un composant programmable et supposons que dans le langage utilis pour exprimer ces tests le OU exclusif se note Le code de ces tests fait partie de la documentation du code C charg de communiquer avec ce composant il se trouve donc dans un commentaire du langage C En C les commentaires sont d limit s par les lex mes et ce qui fait que apparition d un O exclusif de notre langage de test dans un commentaire a pour effet de clore le commentaire Etre dans un commentaire du langage C est donc une condition qui nous interdit d utiliser certains caract res Nous devons donc coder le OU exclusif de nos tests l aide de caract res autoris s mais dans le fichier de tests ce OU exclusif doit appara tre sous la forme De la m me fa on qu un espace de sortie indique comment coder certains symboles un esp
8. e documentation et les notions d espace d en tr e et de sortie permettent de traiter correctement des portions de documen tation exprim es dans un langage formel et ce quelque soit le langage h te de la documentation Cet outil est actuellement en version de d veloppement et devrait tre mis la disposition d tudiants n ayant pas particip son d veloppement d s la rentr e prochaine Nous pourrons alors juger de son impact sur la qualit de la documentation des projets
9. eur fait des hypoth ses sur le fonction nement du composant Ces hypoth ses doivent tre document es afin qu il soit possible de v rifier qu elle sont en accord avec les sp cifications du composant Dans le cas d un composant programmable ces hypoth ses peuvent prendre la forme d un fichier de tests que l outil de programmation pourra faire passer au composant On voit donc que la documentation d un code source peut prendre la forme d un autre code source L exemple suivant montre comment le contenu du fichier de test peut tre inclus dans la documentation Pour cela les pseudo balises xdoc et xdoc ont un attribut out qui permet de pr ciser que leur contenu doit tre plac dans un fichier particulier Documentation de projets en XML 21 lt xdoc gt lt prerequis gt On suppose ici que les sorties lt var gt si lt var gt et lt var gt s2 lt var gt du composant ne sont jamais actives ou inactives en m me temps Le fichier lt fichier href compoZZZ tst gt contient un test v rifiant ce pr requis lt prerequis gt lt xdoc gt lt xdoc out compoZZZ tst gt si xor s2 true lt xdoc gt void uneFonction Notre outil d extraction peut donc tre consid r comme un programme qui rep re des portions balis es dans un fichier source et les crit dans d autres fichiers Mais nous allons voir que lire ou crire un fichier exige certaines pr cautions 6 Espa
10. langer et Yolaine Bourda Une solution est de g n rer automatiquement la DTD d un document partir de sa DTD de base et des extensions utilis es Nous tudions cette possibilit qui permettrait d all ger la syntaxe de la documentation Cet aspect est important car m me si les outils de l environnement de d velop pement permettent de saisir la documentation de fa on naturelle son codage dans les commentaires doit rester lisible Il faut donc absolument viter que les balises et les attributs prennent plus de place que la documentation 5 G n ralisation Extraire de la documentation revient finalement d terminer ce qui est de la documentation dans le fichier source et l crire dans un fichier destination Ceci nous am ne enrichir les marqueurs de documentation afin de pouvoir pr ciser dans quel fichier la documentation doit tre plac e De plus rien n em p che de traiter autre chose que de la documentation au sens classique du terme puisque notre outil n interpr te pas ce qu il extrait La documentation d un projet peut parfois tre exprim e de mani re formelle c est dire exploitable syst matiquement L int r t d une documentation for melle est qu elle ne peut tre interpr t e que d une seule fa on et que sa validit peut tre v rifi e automatiquement Par exemple dans un programme crit en langage C et destin contr ler un composant programmable le programm
11. lles de style XSL permettant d exploiter cette documentation brute b n ficierait de l existence d une DTD de documentation suffisamment g n rale et souple pour s adapter diff rents types de projets Il semble toutefois probable qu une DTD unique ne pourra pas satisfaire tous les besoins de documentation moins de devenir tellement l che qu elle ne d finisse m me plus un v ritable type de document Une autre approche consiste d finir une DTD param trable un peu de la m me fa on qu une classe de documents IATEX peut tre utilis e avec diff rentes options La DTD de base assez pauvre code uniquement la structure minimale pour qu une documentation puisse tre trait e par des outils g n riques archi vage indexation Pour un type de documentation particulier on utilise des extensions de la DTD de base afin de construire une DTD sur mesure Les domaines nominaux d XML permettent d utiliser des l ments de DTDs d extensions dans un document respectant une DTD de base on peut ainsi coder des quations l aide de MathML dans un rapport technique Cela conduit toutefois un document qui n est valide ni par rapport la DTD de base ni par rapport aux DTD d extensions De plus dans notre cas la syntaxe de la documentation serait alourdie car il faudrait pr fixer chaque l ment du nom du domaine associ l extension dans laquelle on souhaite l interpr ter 20 Fr d ric Bou
12. me et qui nous permette de structurer la documentation notre guise Il s agit bien s r d XML 3 D tails pratiques Lorsqu on documente du code il peut tre int ressant d en inclure une portion dans la documentation Dupliquer le code dans la documentation n est pas envisageable car la redondance entra ne t t ou tard des oublis de mise jour Il faut donc int grer la documentation le v ritable code source et non une copie de ce code Cela signifie que tout ce qui appara tra dans la documentation n est pas for c ment dans les commentaires Autrement dit les balises lt xdoc gt et lt xdoc gt ne sont pas forc ment quilibr es dans un commentaire Lorsqu on sort d un commentaire l int rieur d un bloc de documentation le lex me qui fait sor tir du commentaire est ignor de m me que le lex me qui fait entrer dans le commentaire contenant le lt xdoc gt correspondant Il est ainsi possible de faire appara tre des commentaires dans le code int gr la documentation Par exemple le fragment de code C suivant lt xdoc gt La nature des tableaux en C permet d crire des choses comme lt code language C gt assert tab i i tab c est vrai lt code gt qui sont vraies bien que troublantes lt xdoc gt donne le code XML La nature des tableaux en C permet d amp eacute crire des choses comme lt code language C gt assert tabli i tabl
13. raitement des documents Abstract The lack of documentation in most software projects and particularly in our students projects lead us to develop a way to document software by annotating it in comments We generalize this approach to be able to document code in any language and to create documentation in any format However XML is our preferred choice since this work is part of a broader document processing project Mots cl s Documentation annotations documentaires programmation Keywords Documentation documentary annotations programming 1 Introduction A de trop rares exceptions pr s la plupart des logiciels souffrent d un manque de documentation qui nuit leur maintenance et la r utilisation de leur code quand cela ne nuit pas directement leur d veloppement Les quelques rares exceptions sont soit l uvre de d veloppeurs particuli re ment consciencieux soit le r sultat d une programmation litt raire tr s peu r pandue bien que d importance pour notre communaut TEX Nous ne consi d rons pas le cas de JavaDoc qui bien qu int ressant pour documenter les services fournis par du code Java ce que l on appelle une API ne permet de documenter ni l utilisation d un programme ni son fonctionnement interne 1 Application Programming Interface ou interface de programmation d application 16 Fr d ric Boulanger et Yolaine Bourda La programmation litt raire est une bonne id e en ce
14. re Si cette fa on de pr senter les choses ne convient pas il est toujours possible d exploiter ensuite la structure de la documentation afin de changer l ordre dans lequel les diff rentes parties sont pr sent es Pour structurer la documentation IATEX aurait pu convenir mais il est para doxalement trop puissant pour ne d crire qu une structure logique En effet m me si IATEX donne de l importance la structure logique d un document et tente d isoler les probl mes de mise en forme dans des classes de documents et des extensions il s agit quand m me d un langage qui permet de faire de la mise en forme De plus la structure lexicale de TEX rend difficile l analyse d un document tout simplement parce que certaines instructions ont le pou voir de modifier les r gles de grammaire le fait que les programmes autres que TEX qui tentent de lire du ATEX s tranglent au premier changement de catcode non pr vu illustre le probl me l autre extr me HTML est trop pauvre car il ne permet pas de choisir la fa on de structurer la documentation De plus il comporte la fois des balises exprimant une structure logique par exemple lt LI gt pour l ment d une liste et des balises exprimant un aspect visuel lt B gt pour passer en gras Il nous faut 18 Fr d ric Boulanger et Yolaine Bourda donc un langage de balisage logique qui ne permette pas d exprimer des indi cations de mise en for
15. un langage de programmation et un format de documentation Par exemple c2latex de John D RAMSDELL que nous avons utilis avant de lancer ce projet ne fonctionne qu avec C ou C pour cr er de la documentation en IATEX Deux probl mes subsistent les commentaires peuvent ne pas tre enti rement consacr s la documentation et cette documentation doit tre structur e afin de pouvoir tre exploit e automatiquement documentation en ligne environ nement de programmation g rant la documentation etc Le premier probl me est important car les commentaires sont une niche syntaxique dans laquelle trouvent refuge de nombreuses esp ces d annotations outre les commentaires bruts du programmeur on y trouve des indications s mantiques pour divers ou tils de v rification ou d aide la programmation et on risque maintenant d y trouver de la documentation un comble La documentation sera donc isol e dans les commentaires entre deux cha nes de caract res d finissables par luti lisateur et que nous repr sentons ici par les pseudo balises lt xdoc gt et lt xdoc gt Cette fa on d exploiter des structures particuli res dans les commentaires d un langage est assez classique et nous incite consid rer cette approche de la documentation de code comme de la documentation par annotation plut t que comme de la programmation litt raire C est en effet la documentation qui suit le fil du code et non le contrai
Download Pdf Manuals
Related Search