mardi 17 octobre 2017

Générer la documentation à partir des codes sources

Vous cherchez un outil de génération de la documentation à partir des codes sources, on va voir ce que nous avons aujourd'hui sur le marché.

C'est toujours extrêmement pénible pour des raisons de normes qualité essentiellement d'avoir à produire des documents qui sont en fait la "paraphrase du codes sources" je le dis souvent si vous n'êtes pas capable de lire les codes sources ce n'est pas la peine de travailler dans l'édition logicielle.

Mais souvent cet argument est mal compris voir mal perçu. Alors pour faire taire toutes les critiques, écrivons des sources codes correctement documentés et générons automatiquement les docs pour le service qualité à partir de nos sources codes.

C'est compliqué d'avoir déjà des templates de sources codes agréables à utiliser. Donc une des fonctionnalités importante, essentielle du générateur de documentation c'est le "Template personnalisable" ainsi on pourra conserver nos propres Templates si chéris. En effet la plupart du temps les générateurs de doc ont le défaut de vous imposer le Template ...

Par la suite, je suis surpris de découvrir que chaque langage à son générateur de doc. Je tombe alors sur Wikipédia qui nous parle de Doxygen :
http://www.stack.nl/~dimitri/doxygen/
Generate documentation from source code

Wikipédia - Doxygen

https://www.stack.nl/~dimitri/doxygen/
http://www.stack.nl/~dimitri/doxygen/download.html

L'avantage : il est multilangage mais surtout pour le langage C/C++. Personnellement j'ai essayé de le mettre en place à partir des sources codes que j'avais en C/C++ avec des templates que j'affectionne particulièrement, je n'y suis pas arrivé, mes Templates ne lui plaisent sans doute pas mais je ne désespère pas.

Je vous laisse découvrir les autres générateurs sur la page de Wikipédia : Ici

Voilà, je tenais surtout à prendre note de Doxygen. Pour le reste cette génération automatique de doc ce n'est pas et cela ne sera jamais, la panacée. Soit la doc est pourrie soit on pourri le code avec des balises de génération de doc. Le code c'est la bible, la seule chose qui compte mais allez expliquer ça à une bande d'incapables qui trouve cela trop compliqué à lire.

Si vous avez d'autre de vos outils préférés qui featurerisent les même contraintes :
  • Template configurable de façon souple
  • Multilangage
N'hésitez pas à nous en faire part en commentaires.

Have fun!

Aucun commentaire:

Publier un commentaire