Kommentare in TypeScript: JSDoc, @ts-ignore, @ts-expect-error

Kommentare in TypeScript sind JavaScript-Kommentare: // für den Rest einer Zeile und /* */ für einen Block. Ein Blockkommentar, der mit /** beginnt, ist ein Dokumentationskommentar (JSDoc), den Editoren anzeigen, wenn du über das dokumentierte Element hoverst. Dazu liest TypeScript einige besondere Kommentare, die ändern, wie der Compiler deinen Code prüft.

// 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

Ausgabe:

212

Kommentare haben keinen Einfluss auf das Programm. Auch auf die Typprüfung wirken sie sich nicht aus, mit Ausnahme der Direktivkommentare weiter unten.

Einzeilige Kommentare und Blockkommentare

// kommentiert alles danach in der Zeile aus, und das ist auch der schnelle Weg, eine Codezeile zu deaktivieren. /* */ kann mitten in einer Zeile stehen oder viele Zeilen umfassen.

Blockkommentare lassen sich nicht verschachteln. Das erste */ beendet den Kommentar, also geht es schief, wenn du Code einschließt, der schon einen Blockkommentar enthält:

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

Der Compiler versucht dann, this text is now code */ als Code zu lesen, und meldet einen Syntaxfehler. Um einen Bereich mit Blockkommentaren auszukommentieren, setze // vor jede Zeile; die meisten Editoren machen das mit Strg+/ (Cmd+/ unter macOS).

JSDoc-Dokumentationskommentare

Ein Kommentar /** ... */ direkt vor einer Funktion, Klasse, Methode, Eigenschaft, einem Interface oder einer Variablen dokumentiert dieses Element. Editoren zeigen den Text im Hover-Tooltip und in der Autovervollständigung, und Dokumentationsgeneratoren wie TypeDoc machen daraus Referenzseiten. TSDoc, ein von Microsoft gestarteter Standard für diese Kommentare in TypeScript-Code, verwendet für die üblichen Tags dieselbe Syntax:

Wiederhole in einer .ts-Datei die Typen nicht in JSDoc. Die Annotationen im Code sind die Typen, und JSDoc-Typ-Tags werden dort ignoriert: /** @type {string} */ const v: number = 5; kompiliert ohne Beschwerde, weil nur : number zählt.

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

Im Editor zeigt ein Hover über transfer oder balance an jeder Stelle im Projekt diese Beschreibungen.

Code als veraltet markieren

@deprecated erzeugt keinen Compilerfehler. Es sagt Editoren, dass sie jede Verwendung der veralteten Funktion durchgestrichen anzeigen und den Grund beim Hovern nennen sollen. So lenkst du Aufrufer sanft zu einem Ersatz:

/** @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"));

Ausgabe:

$19.99
19.99 EUR

@ts-expect-error und @ts-ignore

Diese beiden Kommentare unterdrücken Typfehler in der folgenden Zeile. Manchmal ist das richtig: bei einem Test, der prüft, wie eine Funktion zur Laufzeit mit falschen Eingaben umgeht, oder bei einer bekannten Lücke in den Typen einer Bibliothek.

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);
    }
}

Ausgabe:

runtime error: text.toUpperCase is not a function

Ohne den Kommentar ist shout(42) ein Compilerfehler (TS2345). Mit ihm kompiliert die Datei, und der Aufruf erreicht die Laufzeit, und genau darum geht es in diesem Test.

Der Unterschied zwischen den beiden Direktiven zeigt sich, wenn der Fehler verschwindet. @ts-expect-error besteht darauf, dass es einen Fehler zu unterdrücken gibt, also wird ein veralteter Kommentar selbst zum Fehler:

// 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 an derselben Stelle bleibt still, solange der Fehler existiert und auch danach. Deshalb ist @ts-expect-error die bessere Wahl: Wenn jemand die Typen repariert, sagt dir der Compiler, dass die Unterdrückung weg kann. Schreibe immer einen Grund hinter die Direktive, wie im Beispiel oben, damit der nächste Leser weiß, warum sie dort steht.

Beide gelten nur für die nächste Zeile und für alle Fehler darin. Um einen ganzen Wert aus der Prüfung zu nehmen, ist ein explizites as unknown as T oder eine Laufzeitprüfung meist klarer als ein Unterdrückungskommentar.

@ts-nocheck und @ts-check

// @ts-nocheck am Anfang einer Datei schaltet die Typprüfung für die ganze Datei ab. Es muss zuerst stehen, vor jedem Code: Weiter unten wird es ignoriert, und die Fehler erscheinen trotzdem.

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

Beim Migrieren einer großen JavaScript-Codebasis ist das nützlich, überall sonst ein Warnsignal.

// @ts-check bewirkt in einer JavaScript-Datei das Gegenteil: Es schaltet die Typprüfung für diese .js-Datei ein, mit Inferenz und JSDoc-Typen, auch wenn checkJs in der tsconfig.json aus ist (die Datei muss über allowJs trotzdem zum Projekt gehören):

// @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'.

In JavaScript-Dateien sind die JSDoc-Tags die Typen. So bekommen viele Projekte eine Typprüfung, ohne Dateien nach .ts umzuwandeln.

Triple-Slash-Direktiven

Ein Kommentar der Form /// <reference ... /> ganz oben in einer Datei ist eine Compiler-Direktive:

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

• types="node" fügt dem Programm ein @types-Paket hinzu, wie ein Eintrag unter "types" in tsconfig.json.
• lib="..." fügt dem Programm eine eingebaute Bibliothek hinzu, wie die Option lib.
• path="..." bindet eine andere Datei ein, meist innerhalb von .d.ts-Dateien.

Im Anwendungscode ersetzen import-Anweisungen und Einstellungen in tsconfig.json fast jede Verwendung; du begegnest diesen Direktiven vor allem in Deklarationsdateien und generiertem Code wie vite-env.d.ts von Vite. Als kurze Demonstration macht lib in dieser Datei eine neuere Array-Methode verfügbar:

/// <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 ]

Kommentare in der kompilierten Ausgabe

tsc übernimmt Kommentare in das JavaScript, das es schreibt. Setze "removeComments": true, um sie wegzulassen; Kommentare, die mit /*! beginnen, bleiben selbst dann erhalten, und das ist die Konvention für Lizenzhinweise:

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

JSDoc-Kommentare werden auch in .d.ts-Dateien übernommen, wenn declaration aktiv ist, sodass die Nutzer einer Bibliothek die Beschreibungen in ihrem Editor sehen.