Commentaires en TypeScript : JSDoc, @ts-ignore et @ts-expect-error

Les commentaires TypeScript sont des commentaires JavaScript : // pour le reste d'une ligne et /* */ pour un bloc. Un commentaire de bloc qui commence par /** est un commentaire de documentation (JSDoc), que les éditeurs affichent quand vous survolez l'élément qu'il documente. En plus de cela, TypeScript lit quelques commentaires spéciaux qui modifient la façon dont le compilateur vérifie votre code.

// A single-line comment runs to the end of the line.

/*
  A block comment can span
  several lines.
*/

/**
 * Converts a temperature from Celsius to Fahrenheit.
 * @param celsius Degrees Celsius.
 * @returns Degrees Fahrenheit.
 */
function toFahrenheit(celsius: number): number {
    return (celsius * 9) / 5 + 32; // a comment after code
}

console.log(toFahrenheit(100)); /* inline block comment */ // 212

Sortie :

212

Les commentaires n'ont aucun effet sur le programme. Ils n'en ont pas non plus sur la vérification des types, à l'exception des commentaires de directive présentés plus bas.

Commentaires sur une ligne et commentaires de bloc

// met en commentaire tout ce qui le suit sur la ligne, c'est aussi le moyen rapide de désactiver une ligne de code. /* */ peut se placer au milieu d'une ligne ou couvrir de nombreuses lignes.

Les commentaires de bloc ne s'imbriquent pas. Le premier */ termine le commentaire, donc entourer du code qui contient déjà un commentaire de bloc casse tout :

/* outer comment /* inner comment */ this text is now code */

Le compilateur essaie alors de lire this text is now code */ comme du code et signale une erreur de syntaxe. Pour mettre en commentaire une zone qui contient des commentaires de bloc, utilisez // sur chaque ligne ; la plupart des éditeurs le font avec Ctrl+/ (Cmd+/ sur macOS).

Commentaires de documentation JSDoc

Un commentaire /** ... */ placé juste avant une fonction, une classe, une méthode, une propriété, une interface ou une variable la documente. Les éditeurs affichent son texte dans l'infobulle de survol et dans l'autocomplétion, et les générateurs de documentation comme TypeDoc en font des pages de référence. TSDoc, un standard pour ces commentaires dans le code TypeScript lancé par Microsoft, utilise la même syntaxe pour les balises courantes :

Dans un fichier .ts, ne répétez pas les types dans JSDoc. Les types, ce sont les annotations du code, et les balises de type JSDoc y sont ignorées : /** @type {string} */ const v: number = 5; compile sans broncher, car seul : number compte.

interface Account {
    /** Balance in cents, to avoid floating-point rounding. */
    balance: number;
}

/**
 * Moves money between two accounts.
 * @param from The account to take the money from.
 * @param to The account that receives it.
 * @param cents Amount in cents. Must not exceed `from.balance`.
 * @throws {RangeError} If the balance is too low.
 */
function transfer(from: Account, to: Account, cents: number): void {
    if (cents > from.balance) {
        throw new RangeError("insufficient funds");
    }
    from.balance -= cents;
    to.balance += cents;
}

const a: Account = { balance: 5000 };
const b: Account = { balance: 0 };
transfer(a, b, 1250);
console.log(a.balance, b.balance); // 3750 1250

Dans un éditeur, survoler transfer ou balance n'importe où dans le projet affiche ces descriptions.

Marquer du code comme déprécié

@deprecated ne provoque pas d'erreur de compilation. La balise demande aux éditeurs d'afficher chaque utilisation de la fonction dépréciée barrée, avec la raison au survol : c'est la manière douce d'orienter les appelants vers un remplaçant.

/** @deprecated Use {@link formatPrice} instead. It ignores the currency. */
function price(cents: number): string {
    return "$" + (cents / 100).toFixed(2);
}

function formatPrice(cents: number, currency: string): string {
    return `${(cents / 100).toFixed(2)} ${currency}`;
}

console.log(price(1999));              // still compiles and runs
console.log(formatPrice(1999, "EUR"));

Sortie :

$19.99
19.99 EUR

@ts-expect-error et @ts-ignore

Ces deux commentaires font taire les erreurs de type de la ligne qui suit. C'est parfois le bon choix : un test qui vérifie comment une fonction gère une entrée invalide à l'exécution, ou une lacune connue dans les types d'une bibliothèque.

function shout(text: string): string {
    return text.toUpperCase();
}

try {
    // @ts-expect-error: testing what happens when JavaScript callers pass a number
    shout(42);
} catch (e) {
    if (e instanceof Error) {
        console.log("runtime error:", e.message);
    }
}

Sortie :

runtime error: text.toUpperCase is not a function

Sans le commentaire, shout(42) est une erreur de compilation (TS2345). Avec lui, le fichier compile et l'appel atteint l'exécution, ce qui est le but de ce test.

La différence entre les deux directives apparaît quand l'erreur disparaît. @ts-expect-error exige qu'il y ait une erreur à supprimer, donc un commentaire périmé devient lui-même une erreur :

// This does not compile: the line below has no type error to suppress.
function shout(text: string): string {
    return text.toUpperCase();
}

// @ts-expect-error
console.log(shout("fixed"));

index.ts(6,1): error TS2578: Unused '@ts-expect-error' directive.

// @ts-ignore au même endroit reste muet, aussi bien tant que l'erreur existe qu'après sa disparition. C'est pourquoi @ts-expect-error est le meilleur choix par défaut : quand quelqu'un corrige les types, le compilateur vous prévient que la suppression peut partir. Ajoutez toujours une raison après la directive, comme dans l'exemple ci-dessus, pour que le prochain lecteur sache pourquoi elle est là.

Les deux ne couvrent que la ligne suivante, et toutes les erreurs de cette ligne. Pour contourner le typage d'une valeur entière, un as unknown as T explicite ou une vérification à l'exécution est en général plus clair qu'un commentaire de suppression.

@ts-nocheck et @ts-check

// @ts-nocheck en haut d'un fichier désactive la vérification des types pour tout ce fichier. Il doit venir en premier, avant tout code : placé plus bas, il est ignoré et les erreurs apparaissent quand même.

// @ts-nocheck
const n: number = "not a number"; // no error reported

Il est utile pendant la migration d'une grosse base de code JavaScript, et c'est un mauvais signe partout ailleurs.

// @ts-check fait l'inverse dans un fichier JavaScript : il active la vérification des types pour ce fichier .js, à partir de l'inférence et des types JSDoc, même quand checkJs est désactivé dans tsconfig.json (le fichier doit tout de même faire partie du projet, via allowJs) :

// @ts-check

/**
 * @param {number} cents
 * @returns {string}
 */
function formatCents(cents) {
    return (cents / 100).toFixed(2);
}

formatCents("12"); // error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

Dans les fichiers JavaScript, les balises JSDoc sont les types, et c'est ainsi que beaucoup de projets obtiennent la vérification des types sans convertir leurs fichiers en .ts.

Directives triple slash

Un commentaire de la forme /// <reference ... /> tout en haut d'un fichier est une directive du compilateur :

/// <reference types="node" />
/// <reference lib="es2023.array" />
/// <reference path="./globals.d.ts" />

• types="node" ajoute un paquet @types au programme, comme si vous le listiez dans "types" dans tsconfig.json.
• lib="..." ajoute une bibliothèque intégrée au programme, comme l'option lib.
• path="..." inclut un autre fichier, surtout utilisé dans les fichiers .d.ts.

Dans le code applicatif, les instructions import et les réglages de tsconfig.json remplacent presque tous les usages ; vous croiserez surtout ces directives dans les fichiers de déclaration et le code généré comme le vite-env.d.ts de Vite. En guise de démonstration rapide, lib rend disponible une méthode de tableau plus récente dans ce fichier :

/// <reference lib="es2023.array" />

const scores = [72, 95, 88];
const ranked = scores.toSorted((a, b) => b - a); // ES2023, copies instead of sorting in place

console.log(ranked); // [ 95, 88, 72 ]
console.log(scores); // [ 72, 95, 88 ]

Les commentaires dans la sortie compilée

tsc conserve les commentaires dans le JavaScript qu'il écrit. Réglez "removeComments": true pour les supprimer ; les commentaires qui commencent par /*! survivent même dans ce cas, c'est la convention pour les en-têtes de licence :

/*! MyLib v1.2.0 | MIT License */

Les commentaires JSDoc sont aussi copiés dans les fichiers .d.ts quand declaration est activé, si bien que les utilisateurs d'une bibliothèque voient les descriptions dans leur éditeur.