TypeScript Comments: JSDoc, @ts-ignore and @ts-expect-error

TypeScript comments are JavaScript comments: // for the rest of a line and /* */ for a block. A block comment starting with /** is a documentation comment (JSDoc), which editors display when you hover over the thing it documents. On top of that, TypeScript reads a few special comments that change how the compiler checks your 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

Output:

212

Comments do not affect the program. They also do not affect type checking, except for the directive comments covered below.

Single-Line and Block Comments

// comments out everything after it on the line, which is also the quick way to disable a line of code. /* */ can sit in the middle of a line or cover many lines.

Block comments do not nest. The first */ ends the comment, so wrapping code that already contains a block comment breaks:

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

The compiler then tries to read this text is now code */ as code and reports a syntax error. To comment out a region that contains block comments, use // on each line; most editors do it with Ctrl+/ (Cmd+/ on macOS).

JSDoc Documentation Comments

A /** ... */ comment directly before a function, class, method, property, interface or variable documents it. Editors show its text in the hover tooltip and in autocompletion, and documentation generators such as TypeDoc turn it into reference pages. TSDoc, a standard for these comments in TypeScript code started by Microsoft, uses the same syntax for the common tags:

In a .ts file, do not repeat the types in JSDoc. The annotations in the code are the types, and JSDoc type tags are ignored there: /** @type {string} */ const v: number = 5; compiles without complaint because only : number counts.

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

In an editor, hovering over transfer or balance anywhere in the project shows these descriptions.

Marking Code as Deprecated

@deprecated does not cause a compile error. It tells editors to show every use of the deprecated function with a strikethrough and the reason on hover, which is the gentle way to steer callers to a replacement:

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

Output:

$19.99
19.99 EUR

@ts-expect-error and @ts-ignore

These two comments silence type errors on the line that follows. Sometimes that is the right call: a test that checks how a function handles bad input at runtime, or a known gap in a library's types.

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

Output:

runtime error: text.toUpperCase is not a function

Without the comment, shout(42) is a compile error (TS2345). With it, the file compiles and the call reaches the runtime, which is the point of this test.

The difference between the two directives shows up when the error goes away. @ts-expect-error insists there is an error to suppress, so a stale comment becomes an error itself:

// 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 in the same place stays silent, both while the error exists and after it is gone. That is why @ts-expect-error is the better default: when someone fixes the types, the compiler tells you the suppression can go. Always add a reason after the directive, as in the example above, so the next reader knows why it is there.

Both only cover the next line and all errors on it. For whole-value escapes, an explicit as unknown as T or a runtime check is usually clearer than a suppression comment.

@ts-nocheck and @ts-check

// @ts-nocheck at the top of a file turns off type checking for that whole file. It has to come first, before any code: placed further down, it is ignored and the errors still appear.

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

It is useful while migrating a large JavaScript codebase, and a smell anywhere else.

// @ts-check does the opposite in a JavaScript file: it turns on type checking for that .js file, using inference and JSDoc types, even when checkJs is off in tsconfig.json (the file still has to be part of the project, through 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'.

In JavaScript files the JSDoc tags are the types, which is how many projects get type checking without converting files to .ts.

Triple-Slash Directives

A comment of the form /// <reference ... /> at the very top of a file is a compiler directive:

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

• types="node" adds a @types package to the program, like listing it in "types" in tsconfig.json.
• lib="..." adds a built-in library to the program, like the lib option.
• path="..." includes another file, mostly used inside .d.ts files.

In application code, import statements and tsconfig.json settings replace almost every use; you mostly meet these directives in declaration files and generated code such as Vite's vite-env.d.ts. As a quick demonstration, lib makes a newer array method available in this file:

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

Comments in the Compiled Output

tsc keeps comments in the JavaScript it writes. Set "removeComments": true to drop them; comments starting with /*! survive even then, which is the convention for license headers:

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

JSDoc comments are also copied into .d.ts files when declaration is on, so users of a library see the descriptions in their editor.