Cahiers
enberg
GUT GUT GUT
m DOCUMENTATION DE PROJETS EN XML
P Frédéric Boulanger , Yolaine Bourda Cahiers GUTenberg, n 35-36 (2000), p. 15-23.
<http://cahiers.gutenberg.eu.org/fitem?id=CG_2000___35-36_15_0>
© Association GUTenberg, 2000, tous droits réservés.
L’accè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.
Documentation de projets en XML
Frédéric Boulanger etYolaine Bourda
SupélecServiceInformatique
Plateau deMoulon
3rueJoliot-Curie, F-91192Gif-sur-Yvettecedex
{Frederic.Boulanger, Yolaine.Bourda}@supelec.fr
Résumé. Lemanquededocumentation delaplupartdes logiciels, etnotamment
de ceux développéspar nos étudiants,nous amèneà envisager uneapproche dela
documentation par annotation du code dans les commentaires. Nous généralisons
cetteapprocheandepouvoirdocumenterducodeenn'importequellangage,etde
créerdeladocumentationàn'importequelformat.XMLesttoutefoisleformatque
nousprivilégionscarce travail s'inscritdansun projetplusvastedetraitementdes
documents.
Abstract. Thelackofdocumentationinmostsoftwareprojects,andparticularlyin
ourstudents'projects,leadustodevelopawaytodocumentsoftwarebyannotatingit
incomments.Wegeneralizethisapproachtobeabletodocumentcodeinanylanguage
andto create documentation inany format. However, XML is our preferred choice
sincethis workispart ofabroaderdocumentprocessingproject.
Mots-clés: Documentation,annotationsdocumentaires,programmation.
Keywords: Documentation,documentaryannotations,programming.
1. Introduction
Àdetropraresexceptionsprès,laplupart deslogicielssourentd'unmanque
dedocumentationquinuitàleurmaintenanceetàlaréutilisationdeleurcode,
quandcelanenuitpasdirectementàleurdéveloppement.
Les quelques rares exceptions sont soit l'÷uvrede développeurs particulière-
ment consciencieux, soit le résultat d'une programmation littéraire très peu
répandue,bienqued'importancepournotrecommunautéT
E
X .Nousneconsi-
dérons pas le cas de JavaDoc qui, bien qu'intéressant pour documenter les
servicesfournisparducodeJava(cequel'onappelleuneAPI 1
),nepermetde
documenterni l'utilisationd'unprogramme,nisonfonctionnementinterne.
Laprogrammationlittéraireestune bonneidéeen cequ'elleregroupelecode
et la documentation dans le même document. C'est en eet une condition
nécessaire (mais hélas pas susante) pour que la documentation soit àjour
visàvisducodequ'elleestcenséedocumenter.
Malheureusement,cestyledeprogrammation,telqu'ilexisteàl'heureactuelle
avecwebetcweb,aquelquesinconvénientsquiexpliquentpeut-êtresonmanque
de succès. Tout d'abord, avant de pouvoir compiler un programme, il faut
extrairelecodedusourceweb.Ilfautpourceladisposerdesoutilsassociésau
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
duméta-source.Danscecas,ondistribueuncodeillisible,cequirevientà
interdireàl'utilisateurpotentieldecomprendrecommentilfonctionneetmême
del'adapteràsaplateformeouàsesbesoins.
L'approchechoisieparD.E. Knuth étaitpertinente àl'époqueàlaquelleT
E X
a été créé, car les outils de développement n'oraient pas ce qu'apportait le
système web,et lesperformances desordinateurs incitaientàne fourniràun
compilateur quelestrictminimumpermettantd'obtenir leprogrammevoulu.
De nosjours,leslangagesde programmationsupportentlamodularitéetdis-
posent demécanismes puissantsde véricationdu respect desinterfaces. Les
performancesdesmachinespermettentdetolérerqu'uncompilateurtraiteplus
delignesdecommentairesquedelignesdecode.Uneautreapprochedelado-
cumentationdecodeestdoncpossible,etnouspensonsqu'ellepeutêtreutilisée
pourtout typede développement,et pasuniquementpourlaprogrammation
enC, C++
ouJava.
2. Principe
Le principe de notre approchede la documentation de code est que ce code
doitrestercompilabledirectement,sanstransformationpréalable.Celapermet
de distribuerle code sourcedocumenté sansobligerlesutilisateursàinstaller
l'outildedocumentation,toutenlesfaisantbénécierdecettedocumentation.
La conséquenceimmédiatede ce principeest queladocumentation setrouve
danslescommentaires.
Sur ce point, nous sommes en retrait par rapport à la programmation litté-
rairepuisquenouscommentonsducodealorsquedansunsourceweb,oncode
lecommentaireduprogramme.Cet inconvénientnous semble largementcom-
penséparlesautresavantagesdenotre approche.
Une autre conséquence de ce principe est que la seule chose que l'outil de
Celapermetdoncdeconstruireunoutilcapabledefonctionneravecplusieurs
langages,etaussid'utiliserplusieurslangagesdansunmêmeprojet.
D'autresoutilsappliquentleprinciped'uncodesourcedirectementutilisable,
maisilsnefonctionnentquepourunlangagedeprogrammationetunformatde
documentation.Par exemple,c2latexdeJohnD.Ramsdell,quenousavons
utilisé avant delancer ce projet,ne fonctionnequ'avec Cou C++
pour créer
deladocumentationenL A
T
E X .
Deuxproblèmessubsistent:lescommentairespeuventnepasêtreentièrement
consacrésàladocumentation,etcettedocumentationdoitêtrestructuréean
depouvoirêtreexploitéeautomatiquement(documentationen ligne,environ-
nementdeprogrammationgérantladocumentationetc).Lepremierproblème
est important car les commentaires sont une niche syntaxique dans laquelle
trouventrefugedenombreusesespècesd'annotations:outrelescommentaires
brutsduprogrammeur,onytrouvedesindicationssémantiquespourdiversou-
tilsdevéricationoud'aideàlaprogrammation,et onrisquemaintenantd'y
trouverdeladocumentationuncomble!Ladocumentationseradoncisolée
danslescommentairesentredeuxchaînesdecaractèresdénissablesparl'uti-
lisateur,etquenousreprésentonsiciparlespseudo-balises<xdoc>et</xdoc>.
Cettefaçond'exploiterdesstructuresparticulièresdanslescommentairesd'un
langage est assez classique, et nous incite à considérer cette approche de la
documentationdecodecommedeladocumentationparannotationplutôt
quecommedelaprogrammationlittéraire.C'esteneetladocumentationqui
suit le l du code et non le contraire. Si cette façon de présenter les choses
ne convientpas, il est toujours possibled'exploiter ensuite la structure de la
documentation, ande changerl'ordredans lequellesdiérentesparties sont
présentées.
Pourstructurerladocumentation,L A
T
E
Xauraitpuconvenir,maisilest para-
doxalementtrop puissant pour ne décrire qu'une structure logique. En eet,
mêmesiL A
T
E
Xdonnedel'importanceàlastructurelogiqued'undocumentet
tente d'isoler les problèmesde mise en forme dans des classes de documents
etdesextensions,ils'agitquand mêmed'unlangagequipermetdefairedela
miseenforme.Deplus,lastructurelexicaledeT
E
Xrenddicilel'analysed'un
document, tout simplement parce que certaines instructions ont le pou-
voirde modier lesrèglesde grammairele faitque lesprogrammesautres
queT
E
X qui tentent delire duL A
T
E
X s'étranglentau premierchangementde
\catcodenonprévuillustreleproblème...
À l'autre extrême, HTML est trop pauvre car il ne permet pas de choisir la
façondestructurerladocumentation.Deplus,ilcomporteàlafoisdesbalises
exprimantune structurelogique(parexemple<LI>pourélémentd'uneliste),
donc unlangagedebalisagelogique quine permette pasd'exprimer desindi-
cationsdemiseenforme,etquinouspermettedestructurerladocumentation
ànotreguise.Ils'agitbiensûrd'XML.
3. Détails pratiques
Lorsqu'ondocumenteducode,ilpeutêtreintéressantd'eninclureuneportion
dans la documentation. Dupliquer le code dans la documentation n'est pas
envisageablecar laredondance entraîne tôtoutarddesoublisde mise-à-jour.
Il faut donc intégrer àla documentation le véritable code source et non une
copie dececode.
Cela signie que tout ce qui apparaîtradans la documentation n'estpas for-
cémentdans lescommentaires. Autrement dit, lesbalises <xdoc>et </xdoc>
ne sont pasforcémentéquilibrées dans un commentaire. Lorsqu'onsort d'un
commentaireà l'intérieur d'unblocde documentation,le lexème qui faitsor-
tir ducommentaireest ignoré, de mêmeque lelexème qui fait entrerdans le
commentairecontenantle</xdoc>correspondant.Ilestainsipossibledefaire
apparaîtredescommentairesdanslecodeintégréàladocumentation.
Parexemple,lefragmentdecodeCsuivant:
/* <xdoc>La nature des tableaux en C permet d'écrire
des choses comme : <code language="C"> */
assert(tab[i] == i[tab]); /* c'est vrai ! */
/* </code> qui sont vraies bien que troublantes.
</xdoc> */
donnelecodeXML:
La nature des tableaux en C permet d'écrire
des choses comme : <code language="C">
assert(tab[i] == i[tab]); /* c'est vrai ! */
</code> qui sont vraies bien que troublantes.
Onremarquequelafermeturedupremiercommentaireetl'ouverturedutroi-
sièmecommentaireontdisparu lorsdel'extractionducodeXML. Parcontre,
le second commentaireest conservétel quel. Onremarque aussi quele `é' de
`écrire'aététransforméenépourrespecterlecodageASCIIstandard
duchierXML.
LanaturedestableauxenCpermet d'écriredeschosescomme:
assert(tab[i] == i[tab]); / c'est vrai ! /
quisontvraiesbienquetroublantes.
Ladocumentationcomplèteestcomposéedeladocumentationextraiteducode,
maisaussi dechiersdedocumentation pure qui pourrontfaireréférence
auxannotationsducodesource.
4. Quelle(s) DTD?
Une fois construite, la documentation doitêtre exploitée de diverses façons:
manueld'utilisation,référencepourdéveloppeurs,descriptiondesalgorithmes
utilisésetc.Chacunedecesvuesdeladocumentationpeututiliserdiérents
média : aideen ligne, documentation papier, documentation interactivedans
unenvironnementdedéveloppement...
L'outild'extractiondedocumentationn'imposeaucunecontraintesurlaDTD,
chacunpeutdoncutiliserlaplusadaptéeàchacundesesprojets.Toutefois,le
développementd'outilsoudefeuillesdestyleXSLpermettantd'exploitercette
documentationbrutebénécieraitdel'existenced'uneDTD dedocumentation
susammentgénéraleet souplepours'adapteràdiérentstypesdeprojets.
Ilsemble toutefoisprobablequ'uneDTD uniquene pourrapassatisfaire tous
lesbesoinsdedocumentation,àmoinsdedevenirtellementlâchequ'ellenedé-
nissemêmeplusunvéritabletypededocument.Uneautreapprocheconsiste
àdénir une DTD paramétrable, unpeu de la même façon qu'uneclasse de
documentsL A
T
E
Xpeutêtreutiliséeavecdiérentesoptions.
La DTD de base,assez pauvre,codeuniquement lastructure minimale pour
qu'une documentation puisse être traitée par des outils génériques archi-
vage, indexation... Pour un type dedocumentation particulier,on utilise des
extensionsdelaDTD debaseandeconstruireuneDTD surmesure.
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
conduittoutefois àundocumentqui n'est valideni parrapport àlaDTD de
base,niparrapportauxDTDd'extensions.Deplus,dansnotrecas,lasyntaxe
deladocumentationseraitalourdiecarilfaudraitpréxerchaqueélémentdu
Une solutionestdegénérerautomatiquementlaDTDd'undocumentàpartir
de saDTD de baseet desextensions utilisées.Nousétudionscette possibilité
qui permettraitd'allégerlasyntaxedeladocumentation.
Cetaspectestimportantcar,mêmesilesoutilsdel'environnementdedévelop-
pementpermettentdesaisir ladocumentationde façonnaturelle,soncodage
danslescommentairesdoitresterlisible.Ilfautdoncabsolumentéviterqueles
balisesetlesattributsprennentplusdeplacequeladocumentation.
5. Généralisation
Extraire deladocumentationrevientnalementàdéterminercequi est dela
documentationdans lechiersource, et àl'écriredans unchierdestination.
Ceci nous amène àenrichir les marqueursde documentation an de pouvoir
préciserdansquelchierladocumentationdoitêtreplacée.Deplus,rienn'em-
pêchedetraiterautrechosequedeladocumentationausensclassiqueduterme
puisquenotreoutiln'interprètepasce qu'ilextrait.
Ladocumentationd'unprojetpeutparfoisêtreexpriméedemanièreformelle,
c'est-à-dire exploitablesystématiquement. L'intérêt d'unedocumentation for-
melleestqu'ellenepeutêtreinterprétéequed'uneseulefaçon,etquesavalidité
peutêtrevériéeautomatiquement.
Parexemple,dansunprogrammeécritenlangageCet destinéàcontrôlerun
composantprogrammable,leprogrammeurfaitdeshypothèsessurlefonction-
nementducomposant.Ceshypothèsesdoiventêtredocumentéesanqu'ilsoit
possibledevérierqu'ellesontenaccordaveclesspécicationsducomposant.
Danslecasd'uncomposantprogrammable,ceshypothèsespeuventprendrela
formed'unchierdetestsquel'outildeprogrammationpourrafairepasserau
composant.Onvoitdoncqueladocumentationd'uncodesourcepeutprendre
laformed'unautrecodesource!
L'exemple suivant montre comment le contenu du chier de test peut être
inclus dansladocumentation.Pourcela,lespseudo-balisesxdocet/xdocont
un attribut outqui permet de préciser queleur contenudoit être placé dans
/* <xdoc><prerequis>
On suppose ici que les sorties <var>s1</var>
et <var>s2</var> du composant ne sont jamais
actives ou inactives en même temps.
Le fichier <fichier href="./compoZZZ.tst"/>
contient un test vérifiant ce prérequis.
</prerequis>
</xdoc>
<xdoc out="./compoZZZ.tst">
s1 .xor. s2 = true;
</xdoc>
*/
void uneFonction() {
...
}
Notre outil d'extraction peut donc être considéré comme unprogramme qui
repère des portions balisées dans un chier source et les écrit dans d'autres
chiers.Maisnousallonsvoirquelireouécrireunchierexigecertaines
précautions.
6. Espaces d'entrée et de sortie
Nousavonsdéjàvuquelorsqu'onécritdansunchierXML,certainscaractères
littérauxdoiventêtretraduits:un&doitêtreécrit&.Sionécrivaitdans
unchierL A
T
E
X ,lemême&devraitêtreécrit\&.
Lanécessitédecodercertainscaractèresdefaçonparticulièrepeutêtrerepré-
sentée par la notion d'espace de sortie. Ainsi, dans l'espace de sortie XML,
l'esperluette se code & et le signe inférieur strict <. Il faut bien
noter qu'il s'agit de l'esperluette et du signe inférieur strict en tant que
symboles, pasen tantquecaractères. En eet,une baliseXML débuteparle
caractère <,qui nedoit pasêtre remplacépar <.Demême, le caractère&
délimite àgauchelesentitésXML, et lorsqu'il est utilisé pourcela, il nedoit
pasêtreremplacé par&.
Lanotiond'espacedesortiepermetànotreoutild'extrairedeladocumentation
sousd'autresformatsqu'XMLil suraitdecoderl'espacedesortieL A
T
E X
dansnotreoutilpourqu'ilpermetted'écriredesdocumentsnormauxet
decréerdeschiersendiverslangages.Maiscette notionn'estpassusante:
il est aussinécessaired'indiquer commentinterpréterlescaractèresdu chier
Nousavonsvudansunexemplequelecaractère`é'danslechiersourceétait
traduitenédansl'espacedesortieXML.Cettefaçondedireleschoses
est partiellement fausse : c'est en eet le symbole e accent aigu qui est
codéainsi enXML. Ilmanquece qui apermis àl'outilde reconnaîtreun e
accentaigu danslecaractère `é'duchiersource.Cequ'on alu n'estqu'un
nombre, et ilfaut connaîtrelecodagedudocumentpourl'interprétercomme
un`é'.Toutefois,l'interprétationducontenuduchiersourceneselimite pas
àl'utilisationd'uncodagedescaractères.
Reprenonsnotreexempleduchierdetestspouruncomposantprogrammable,
etsupposonsquedanslelangageutilisépourexprimercestests,leOUexclusif
senote*/.LecodedecestestsfaitpartiedeladocumentationducodeCchargé
de communiqueravec ce composant; il setrouve doncdans un commentaire
dulangageC.EnC,lescommentairessontdélimitésparleslexèmes/*et */,
ce quifaitque l'apparitiond'un OUexclusif denotrelangage detest dansun
commentaireapoureetdeclorelecommentaire...
ÊtredansuncommentairedulangageCestdoncuneconditionquinousinterdit
d'utilisercertainscaractères.NousdevonsdonccoderleOUexclusifdenostests
à l'aide de caractères autorisés, mais dans le chier de tests, ce OU exclusif
doit apparaître sous la forme */. De la même façon qu'un espace de sortie
indiquecommentcodercertainssymboles,unespaced'entréeindiquecomment
interpréter certainscaractères. Dans notrecas, on pourra déciderde coder le
OUexclusifsouslaforme.xor.parexemple,etconstruireunespaced'entrée
danslequel.xor.s'interprèteen*/.
7. Conclusion
L'approchedeladocumentationquenousproposonstentedeconservercertains
bonsaspectsdelaprogrammationlittérairetoutens'appuyantplusfortement
surlesmécanismesfournisparleslangagesdeprogrammationactuels.Elleper-
metladistributionducodesourcedocumentéenéliminantl'étaped'extraction
du code compilable, ce qui lui permet de plus de s'appliquer à tout langage
de programmationdont onsait isolerlescommentaires,et d'utiliser plusieurs
langagesdansunmêmeprojet.
En choisissantXML pour structurer la documentation, nous souhaitons per-
mettre à des outils de projeter diérentes vues de cette documentation
qui pourronts'adresseràdiérentspublics: utilisateurs,programmeurs,tech-
niciensdemaintenance.Chacunedecesvuespourradeplusêtreprésentéesur
diérentsmédia:manuelpapier,aideenligne,systèmedemaintenanceassistée
Lamiseaupointd'unsystèmedeDTDsparamétrablespermettradestructurer
ladocumentationdelamanièrelaplusappropriée,toutenbénéciantd'outils
capablesdelatraiterselonune DTDdebase.
Lesupportdeplusieurschiersdedocumentationetlesnotionsd'espaced'en-
tréeetdesortiepermettentdetraitercorrectementdesportions dedocumen-
tationexpriméesdansunlangageformel, etcequelquesoitlelangagehôtede
ladocumentation.
Cet outil est actuellementen versiondedéveloppementet devrait êtremis à
la disposition d'étudiants n'ayant pas participé à son développement dès la
rentréeprochaine.Nouspourronsalorsjugerdesonimpactsurlaqualitédela
