Komentarze w TypeScript: JSDoc, @ts-ignore i @ts-expect-error

Komentarze w TypeScript to komentarze JavaScriptu: // do końca linii i /* */ dla bloku. Komentarz blokowy zaczynający się od /** to komentarz dokumentacyjny (JSDoc), który edytory wyświetlają po najechaniu na element, który opisuje. Do tego TypeScript odczytuje kilka specjalnych komentarzy, które zmieniają sposób, w jaki kompilator sprawdza kod.

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

Wynik:

212

Komentarze nie wpływają na program. Nie wpływają też na sprawdzanie typów, z wyjątkiem komentarzy z dyrektywami opisanych niżej.

Komentarze jednoliniowe i blokowe

// zakomentowuje wszystko, co jest po nim w linii, i to też szybki sposób na wyłączenie linii kodu. /* */ może stać w środku linii albo obejmować wiele linii.

Komentarze blokowe się nie zagnieżdżają. Pierwsze */ kończy komentarz, więc opakowanie kodu, który już zawiera komentarz blokowy, psuje go:

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

Kompilator próbuje wtedy odczytać this text is now code */ jako kod i zgłasza błąd składni. Żeby zakomentować fragment, który zawiera komentarze blokowe, użyj // w każdej linii; większość edytorów robi to skrótem Ctrl+/ (Cmd+/ na macOS).

Komentarze dokumentacyjne JSDoc

Komentarz /** ... */ bezpośrednio przed funkcją, klasą, metodą, właściwością, interfejsem albo zmienną dokumentuje ją. Edytory pokazują jego tekst w dymku po najechaniu kursorem i w podpowiedziach, a generatory dokumentacji, takie jak TypeDoc, zamieniają go w strony referencyjne. TSDoc, standard takich komentarzy w kodzie TypeScript zapoczątkowany przez Microsoft, używa tej samej składni dla popularnych znaczników:

W pliku .ts nie powtarzaj typów w JSDoc. Typami są adnotacje w kodzie, a znaczniki typów JSDoc są tam ignorowane: /** @type {string} */ const v: number = 5; kompiluje się bez zastrzeżeń, bo liczy się tylko : number.

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

W edytorze najechanie na transfer albo balance w dowolnym miejscu projektu pokazuje te opisy.

Oznaczanie kodu jako przestarzałego

@deprecated nie powoduje błędu kompilacji. Każe edytorom pokazywać każde użycie przestarzałej funkcji jako przekreślone, z powodem w dymku, co jest łagodnym sposobem na skierowanie wywołujących do zamiennika:

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

Wynik:

$19.99
19.99 EUR

@ts-expect-error i @ts-ignore

Te dwa komentarze wyciszają błędy typów w linii, która po nich następuje. Czasem to słuszna decyzja: test, który sprawdza, jak funkcja radzi sobie w czasie działania ze złymi danymi, albo znana luka w typach biblioteki.

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

Wynik:

runtime error: text.toUpperCase is not a function

Bez komentarza shout(42) to błąd kompilacji (TS2345). Z komentarzem plik się kompiluje, a wywołanie dociera do czasu działania, i o to chodzi w tym teście.

Różnica między tymi dwiema dyrektywami ujawnia się, gdy błąd zniknie. @ts-expect-error wymaga, żeby był błąd do wyciszenia, więc nieaktualny komentarz sam staje się błędem:

// 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 w tym samym miejscu milczy, zarówno gdy błąd istnieje, jak i po jego zniknięciu. Dlatego @ts-expect-error to lepszy wybór domyślny: gdy ktoś naprawi typy, kompilator powie ci, że wyciszenie można usunąć. Zawsze dopisz powód po dyrektywie, jak w przykładzie wyżej, żeby następna osoba czytająca kod wiedziała, dlaczego tam jest.

Obie dyrektywy obejmują tylko następną linię i wszystkie błędy w niej. Przy obchodzeniu typu całej wartości jawne as unknown as T albo sprawdzenie w czasie działania jest zwykle czytelniejsze niż komentarz wyciszający.

@ts-nocheck i @ts-check

// @ts-nocheck na początku pliku wyłącza sprawdzanie typów dla całego pliku. Musi być pierwsze, przed jakimkolwiek kodem: umieszczone niżej jest ignorowane, a błędy nadal się pojawiają.

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

Przydaje się przy migracji dużego projektu JavaScript, a wszędzie indziej to sygnał ostrzegawczy.

// @ts-check robi odwrotnie w pliku JavaScript: włącza sprawdzanie typów dla tego pliku .js, korzystając z wnioskowania i typów JSDoc, nawet gdy checkJs jest wyłączone w tsconfig.json (plik nadal musi należeć do projektu, przez 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'.

W plikach JavaScript znaczniki JSDoc są typami i w ten sposób wiele projektów ma sprawdzanie typów bez przerabiania plików na .ts.

Dyrektywy z potrójnym ukośnikiem

Komentarz w postaci /// <reference ... /> na samym początku pliku to dyrektywa kompilatora:

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

• types="node" dodaje do programu pakiet @types, jak wpisanie go w "types" w tsconfig.json.
• lib="..." dodaje do programu wbudowaną bibliotekę, jak opcja lib.
• path="..." dołącza inny plik, używane głównie w plikach .d.ts.

W kodzie aplikacji instrukcje import i ustawienia tsconfig.json zastępują prawie każde użycie; te dyrektywy spotkasz głównie w plikach deklaracji i w kodzie generowanym, takim jak vite-env.d.ts z Vite. Na szybki pokaz: lib udostępnia w tym pliku nowszą metodę tablic:

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

Komentarze w skompilowanym wyniku

tsc zachowuje komentarze w JavaScripcie, który zapisuje. Ustaw "removeComments": true, żeby je usunąć; komentarze zaczynające się od /*! zostają nawet wtedy, co jest konwencją dla nagłówków licencji:

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

Komentarze JSDoc są też kopiowane do plików .d.ts, gdy włączone jest declaration, więc użytkownicy biblioteki widzą opisy w swoim edytorze.