memo_jsdoc.md

JSDoc, c'est l'outil de génération automatique de documentation. Il transforme des commentaires et des fichiers Markdown comme celui-ci en une masse de pages web lisibles même par un autiste semi-aveugle à quiil manquerait un module de sémantique.

La doc de JSDoc, paradoxalement un peu aride : Use JSDoc

Les bases

JSDoc fonctionne sur la base de token de la forme @truc dans des commentaires avec seulement 2 *. C'est en lisant ces tokens qu'il génère sa documentation. JSDoc comprend le javascript, mais ne génère pas automatiquement les tags à partir du code. Ex :

/**
 * @function renv Fonction bidon
 * @arg a - Nombre à renvoyer
 */
function renv(a:number) { return a; }

Là on lui donne uyne description d'une fonction et une documentation de son argument, mais pas le type de a, qu'il n'infère pas seul. Ca peut mener à des différences entre le vrai type et le type documenté, surtout quand le code évolue vite, mais ça peut aussi permettre de configurer complètement la doc à la fonction près, ce qui est pas mal non plus.

JSDoc est configuré via le fichier jsdoc_config.json à la racine du projet. Ce fichier précise à JSDoc quels fichiers traiter, où ranger ses résultats, quels extensions utiliser, etc...

Pour lancer jsdoc la commande est : jsdoc --configure jsdoc_config.json

Ou plus simplement : npm run doc pour un package.json à jour.

Nous avons fait le choix de ne pas mettre la documentation de sigma sur le git car les nombreux fichiers html alourdissaient inutilement le répertoire. Tout nouveau développeur du projet est donc invité à lanncer JSDoc pour régénérer la doc en local !

Les détails

JSDoc et VSCode

JSDoc et VSCode marchent très bien ensemble ; VSCode générera automatiquement les tags afférents à une fonction déjà rédigée si vous commencez un commentaire juste avant cete fonction.

L'arborescence

JSDoc n'est pas bon pour faire appraître une arborescence de fichiers. Il va afficher toutes les fonctions qu'il parse sur la page d'accueil, indépendamment de leur nombre ou de leur emplacement dans le projet. Pour rendre la documentation lisible et faire apparître une vraie arborescence, il convient d'utiliser des namespace ou des classes, quitte à ce qu'elles soient purement statiques, pour factoriser le code par bloc de sens.

La factorisation de code dans des classes étant en soit une bonne pratique et permettant aussi au développeur de réfléchir à l'organisation de son programme, cette pratique devrait être encouragée de manière globale dans tout le projet.

Les fichiers. md

JSDoc a deux façons simples d'intégrer des fichiers Mardown dans la doc ; un README en page d'accueil, ou un tutoriel comme celui-ci. Tous les tutoriels doivent être mis dans le même dossier avec des fichiers de config .json pour définir une arborescence de tutoriels propres.