Une fonction bien nommée reste muette sur l'unité de ses arguments, sur ce qu'elle rend quand elle échoue et sur ce qui est facultatif.
JSDoc met ces réponses juste au-dessus, dans un commentaire que l'éditeur affiche à l'appel et que TypeScript sait vérifier.
Définition
JSDoc est une convention d'écriture des commentaires JavaScript. Un bloc ouvert par /** et composé de balises précédées d'un arobase décrit les paramètres, la valeur rendue et les types associés. Le langage l'ignore, les outils non.
/**
* Calcule le montant TTC d'une facture.
*
* @param {number} montantHT Le montant hors taxes, en euros.
* @param {number} [taux] Le taux de TVA, 0.2 par défaut.
* @returns {number} Le montant TTC arrondi au centime.
*/
function totalTTC(montantHT, taux = 0.2) {
return Math.round(montantHT * (1 + taux) * 100) / 100;
}
console.log(totalTTC(19)); // 22.8Les crochets autour de taux signalent un Paramètre par défaut, donc facultatif à l'appel. L'éditeur reprend ces trois lignes dans son infobulle, et la complétion connaît désormais la nature de chaque argument.
Les balises du quotidien
| Balise | Ce qu'elle décrit |
|---|---|
| @param | Un argument : son type, son nom, son rôle |
| @returns | La valeur rendue, et à quelle condition |
| @type | Le type d'une variable ou d'une constante |
| @typedef | Un type nommé, réutilisable dans tout le fichier |
| @property | Un champ du type déclaré juste au-dessus |
| @throws | L'Error que la fonction peut lever |
Six balises suffisent à couvrir la quasi-totalité des besoins. Les autres, une trentaine, servent surtout aux générateurs de documentation.
Typer un fichier .js sans compilateur
Un commentaire // @ts-check en tête de fichier, ou l'option checkJs du projet, et le vérificateur de TypeScript traite le JavaScript exactement comme du TypeScript, en lisant les types dans les commentaires.
/**
* @typedef {object} Facture
* @property {number} id
* @property {number} montant
* @property {"brouillon" | "payee"} statut
*/
/** @type {Facture} */
const facture = { id: 42, montant: 19, statut: "regle" };
// Type '"regle"' is not assignable to type '"brouillon" | "payee"'.Le fichier reste un .js exécutable tel quel : aucune étape de compilation, aucun outil supplémentaire à installer. C'est la voie la plus courte pour typer une base existante.
Questions fréquentes
JSDoc remplace-t-il TypeScript ?
Sur un petit projet, souvent oui : les mêmes vérifications, sans compilation. Sur une base plus grosse, l'écriture devient verbeuse et les fonctionnalités avancées, comme les types conditionnels, se déclarent mal en commentaire. La bascule vers de vrais fichiers TypeScript arrive alors d'elle-même.
Faut-il commenter chaque fonction ?
Non. Une fonction courte au nom explicite se documente toute seule, et un commentaire qui répète le nom du paramètre n'apporte rien. Réservez JSDoc aux fonctions exportées, à celles dont le contrat n'est pas évident, et à tout ce qui a des paramètres facultatifs.
Que se passe-t-il quand le commentaire ment ?
Sans @ts-check, rien du tout : le commentaire est du texte libre et personne ne le confronte au code. Avec la vérification activée, il devient une contrainte comme une autre, et une annotation fausse produit une erreur au même titre qu'un mauvais argument. C'est tout l'intérêt de l'activer.