Vive la doc avec compodoc !

Introduction :

Tout développeur s'est, au moins une fois dans sa vie professionnelle, confronté à une tâche qu'il n'apprécie guère : la documentation de leur code.

Cet article va parler de Compodoc. Un outil qui va générer automatiquement la documentation de votre projet Angular, notamment les modules, components, injectables, pipes, routes, classes et directives.

En plus d'être super clair et bien organisé, il a l'avantage d'être un outil de documentation vivant, dans le sens où le contenu colle parfaitement avec le code du projet Angular. 

Allons voir ça au travers d'un exemple. Prêt ? Go !

Installation

Rien de plus simple pour installer compodoc : 

npm install -g @compodoc/compodoc

Une fois l'installation terminée : 

Lancement

Pour générer et afficher la documentation, il est conseillé de créer un script dans votre package.json, comme ceci : 

Ainsi, pour lancer votre serveur compodoc, rien de plus simple : 

npm run doc

Lorsque vous lancer la génération, un répertoire vient se créé dans votre projet : 

Votre documentation est terminée !

Vous pouvez la visualiser : http://localhost:8080

Tour d'horizon des pages

Dans le menu de gauche, vous verrez l'ensemble de vos modules, components, directives, classes, injectables et pipes.

Je vous invite à cliquer sur chacun d'eux pour rentrer dans le détail et permettre de voir leurs dépendances au travers des imports/exports. Les @input / @output sont également affichés au niveau des modules.

Pour comprendre sur le pourquoi du comment ?

Compodoc s'appuie sur les tags JSDoc.

Exemple : 

/**
 * @param {string} target  The target to process
 * @returns The processed target number
 */
function calculPts(target:string):number;

Vous avez la possibilité de compléter cette documentation en rajoutant d'autres tags (que vous trouverez ici :  https://jsdoc.app/).

Conclusion

Pour les développeurs Angular qui ne connaissaient pas Compodoc, je vous conseille fortement de l'installer sur vos projets. La documentation ne fait plus partie des tâches ingrates que vous faites ; Compodoc vient accompagner le développeur comme outil de documentation mais aussi d'analyse de son code.