Le fichier exemple.zip contient plusieurs fichiers. Nous allons pr‚senter les outils de documentation de Solucorp. Dans ce document, le mot documentation r‚fŠre … quelques formes d'information qui aident les programmeurs … comprendre et utiliser des librairies logiciels. Nous ne faisons aucunement r‚f‚rence … de la documentation pour usager. Fournir une documentation fiable et … jour n'est pas facile. Une m‚thodologie bas‚e sur un systŠme trop ind‚pendant du code source ne fonctionnera pas. Une documentation fiable (complŠte et … jour) aide … la r‚utilisation du code. Voici, … notre avis, les ‚l‚ments essentiels … toute r‚utilisation de code. A) Les fonctions doivent ˆtre facile … localiser. Les programmeurs ont besoin d'indexs, de sommaires, et r‚f‚rences. Si une fonction ou systŠme existe, mais n'est pas facile … localiser, il sera refait (duplicat‚). B) Une fonction ou groupe de fonctions doit ˆtre facile … comprendre. Chaque fonction d'un systŠme doit ˆtre document‚e, simplement et la documentation doit ˆtre trŠs proche du code lui-mˆme. C) Le code doit fonctionn‚ correctement ! Le kit de documentation Solucorp part du principe que la documentation d'un module doit ˆtre dans le code source, imm‚diatement … cot‚ de la d‚claration formelle du module (fonction). Si cette documentation n'est pas fiable et … jour, aucune ne le sera jamais. Le format de pr‚sentation est simple. La premiŠre ligne de commentaire avant la d‚claration d'une fonction est un description brŠve de la fonction. Tous les commentaires entre cette ligne et la d‚claration donne une explication plus complŠte. Cela dit ce que la fonction fait et ne fait pas, quand cette fonction doit ˆtre appel‚e, ce qui am‚liorerait cette fonction, les valeurs retourn‚es, etc ... Les fichiers sources (source*.c) fournis pr‚sentent un systŠme de fonctions avec une documentation trŠs brŠve. Le fichier makefile contient une cible "doc" … la fin, qui montre la s‚rie de commande utilis‚e pour mettre … jour le kit de documentation. A partir des fichiers sources, proto (l'extracteur de prototypes) extrait les prototypes et les commentaires entourant les d‚claration. Le fichier xsys.nap est produit. Naperm formatte trois fichiers … partir de xsys.nap. xsys.nas : Toutes les fonctions sont pr‚sent‚es en ordre alphab‚tique accompagn‚es de la description brŠve. xsys.nai : C'est un index permutt‚ du fichier xsys.nas. xsys.nah : C'est un historique de toutes les r‚visions qui ont ‚t‚ faites au projet xsys. On peut retrouver quand une fonction a ‚t‚ ajout‚e au projet. On voie les fonctions qui ont ‚t‚ ‚limin‚es. Les diff‚rentes r‚visions d'une fonction apparaissent aussi. Si un programmeur a une connaissance minimale du systŠme Xsys, ces trois fichiers lui-permettront de localiser rapidement les diff‚rentes fonctions requises pour son projet. Si, par contre, le systŠme est nouveau pour lui, et que Xsys possŠde une centaine de fonctions, un autre document sera requis. Un document g‚n‚ral sur Xsys devra ˆtre r‚alis‚e. Il pr‚sentera les fonctions d'une fa‡on organis‚e. Ce genre de document est difficile … produire, impossible … entretenir. Il est g‚n‚ralement volumineux. Il est souvent erron‚. Pour toutes ces raisons, il n'est jamais lu. Il y a toutefois un moyen de produire un tel document simplement. Si la documentation dans les sources est pr‚cise, alors un document peut ˆtre formatt‚ … partir de cela. Le fichier xsys.doc est un squelette du manuel de r‚f‚rence du systŠme xsys. Il contient un petite introduction, une pr‚sentation du systŠme et une classification de chacune des fonctions de xsys. A partir de xsys.doc et xsys.nap, le fichier xsys.ref est produit. Ce fichier est le manuel de r‚f‚rence. Il est toujours … date (aussi … date que la documentation dans les sources). Nadoc est le programme qui produit ce fichier. It mentionne toutes les fonctions de xsys qui ne sont pas classifi‚es dans xsys.doc. Il mentionne aussi les fonctions classifi‚es qui n'existent plus dans le systŠme xsys.