JSDoc

JSDoc est une norme de documentation pour annoter le code JavaScript. Pour ajouter un commentaire JSDoc, commencez par /** (notez le double astérisque) et ajoutez des métadonnées à l'aide de la syntaxe @tag info.

Avec JSDoc, vous pouvez fournir des informations aux autres développeurs :

/** @license Apache-2.0 */

/**
* @author Alice
* @description Cette fonction ne fait rien
*/
function test() {
  return null;
}

et à votre IDE (vous devrez peut-être ajuster la configuration).

/** @type {null | string} */
let myVar = null;

myVar = 45; // Avertissement de l'IDE : Le type 'number' n'est pas assignable au type 'string'

Avec JSDoc, vous pouvez extraire la documentation de votre code dans des fichiers HTML, afficher des avertissements relatifs aux types dans votre IDE, ou même vérifier les types de vos fichiers avant un push Git (par exemple, dans le cadre d'un hook pre-commit ou pre-push).

Documentation

JSDoc est principalement conçu pour la documentation. Vous pouvez annoter des fichiers, des classes, des fonctions et des variables. Contrairement aux simples commentaires, JSDoc permet à votre IDE de signaler les fonctions obsolètes ou d'indiquer les événements émis par une classe. Des outils tels que jsdoc/jsdoc et jsdoc-to-markdown recherchent les balises JSDoc et les transforment en documentation HTML ou Markdown.

Voici quelques exemples de ce que vous pouvez documenter avec JSDoc :

• Informations légales : auteur, licence et copyright.

• Versionnage : version, obsolète et depuis (date d'ajout d'une fonctionnalité).

• Explication du code : description, événements émis ou reçus et dépendances.

Informations sur les types

JSDoc prend en charge les annotations de type que votre IDE utilise pour vérifier les types dans votre code. L'ajout de types est sans doute la meilleure aide pour le développement avancé en JavaScript. Ils activent l'autocomplétion, les avertissements et les erreurs, et permettent de détecter de nombreux bogues pendant le développement.

JSDoc peut être utilisé naturellement avec TypeScript, offrant une intégration facile entre les fichiers *.js, *.ts et *.d.ts.

Avantages par rapport à TypeScript

Les déclarations JSDoc sont simplement des commentaires ; la transpilation n'est pas nécessaire (c'est-à-dire la transformation de *.ts en *.js). Dans de nombreux cas, il n'est pas nécessaire d'utiliser des transpileurs, des fichiers de mappage de sources (source map) ou des répertoires source et de sortie séparés. Profitez de la puissance des types avec la simplicité de JavaScript !

Limitations par rapport à TypeScript

JSDoc est plus verbeux que TypeScript, en particulier pour les types avancés. De plus, JSDoc ne permet pas d'ajouter de mots-clés à JavaScript ; il ne prend pas en charge les énumérations, les décorateurs ni les opérateurs d'assertion non nulle.

Par ailleurs, certains frameworks dépendent des fonctionnalités de TypeScript. Par exemple, NestJS utilise les décorateurs expérimentaux de TypeScript, ce qui rend ce dernier obligatoire.

Conclusion

JSDoc vous permet de typer votre code et d'ajouter de la documentation simplement en écrivant des commentaires. Bien que sa syntaxe ne soit pas aussi élégante que celle de TypeScript, c'est une alternative plus simple et qui permet d'aller assez loin. De plus, JSDoc fonctionne également avec les fichiers TypeScript.

Avez-vous déjà utilisé JSDoc pour typer votre projet ?