Comentarios en TypeScript: JSDoc, @ts-ignore y @ts-expect-error

Los comentarios de TypeScript son los de JavaScript: // para el resto de una línea y /* */ para un bloque. Un comentario de bloque que empieza por /** es un comentario de documentación (JSDoc), que los editores muestran al pasar el ratón por encima de lo que documenta. Además, TypeScript lee algunos comentarios especiales que cambian cómo el compilador comprueba tu código.

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

Salida:

212

Los comentarios no afectan al programa. Tampoco afectan a la comprobación de tipos, salvo los comentarios de directiva que se explican más abajo.

Comentarios de una línea y de bloque

// comenta todo lo que viene detrás en la línea, y también es la forma rápida de desactivar una línea de código. /* */ puede ir en medio de una línea o abarcar muchas.

Los comentarios de bloque no se anidan. El primer */ cierra el comentario, así que envolver código que ya contiene un comentario de bloque lo rompe:

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

El compilador intenta entonces leer this text is now code */ como código e informa un error de sintaxis. Para comentar una zona que contiene comentarios de bloque, usa // en cada línea; la mayoría de los editores lo hace con Ctrl+/ (Cmd+/ en macOS).

Comentarios de documentación JSDoc

Un comentario /** ... */ justo antes de una función, clase, método, propiedad, interfaz o variable la documenta. Los editores muestran su texto en el tooltip al pasar el ratón y en el autocompletado, y los generadores de documentación como TypeDoc lo convierten en páginas de referencia. TSDoc, un estándar para estos comentarios en código TypeScript que empezó Microsoft, usa la misma sintaxis para las etiquetas habituales:

En un archivo .ts, no repitas los tipos en JSDoc. Los tipos son las anotaciones del código, y ahí las etiquetas de tipo de JSDoc se ignoran: /** @type {string} */ const v: number = 5; compila sin quejas porque solo cuenta : 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

En un editor, al pasar el ratón por encima de transfer o balance en cualquier parte del proyecto se ven estas descripciones.

Marcar código como obsoleto

@deprecated no provoca un error de compilación. Indica a los editores que muestren cada uso de la función obsoleta tachado y con el motivo al pasar el ratón, que es la forma suave de llevar a quien la llama hacia la alternativa:

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

Salida:

$19.99
19.99 EUR

@ts-expect-error y @ts-ignore

Estos dos comentarios silencian los errores de tipos de la línea siguiente. A veces es lo correcto: un test que comprueba cómo trata una función una entrada incorrecta en tiempo de ejecución, o un hueco conocido en los tipos de una librería.

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

Salida:

runtime error: text.toUpperCase is not a function

Sin el comentario, shout(42) es un error de compilación (TS2345). Con él, el archivo compila y la llamada llega a la ejecución, que es justo lo que busca este test.

La diferencia entre las dos directivas aparece cuando el error desaparece. @ts-expect-error exige que haya un error que suprimir, así que un comentario obsoleto se convierte él mismo en un error:

// 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 en el mismo sitio se queda callado, tanto mientras existe el error como cuando ya no está. Por eso @ts-expect-error es la mejor opción por defecto: cuando alguien arregla los tipos, el compilador te avisa de que la supresión sobra. Añade siempre un motivo después de la directiva, como en el ejemplo de arriba, para que quien lea después sepa por qué está ahí.

Las dos cubren solo la línea siguiente y todos sus errores. Para saltarse la comprobación de un valor entero, un as unknown as T explícito o una comprobación en tiempo de ejecución suele ser más claro que un comentario de supresión.

@ts-nocheck y @ts-check

// @ts-nocheck al principio de un archivo desactiva la comprobación de tipos en todo ese archivo. Tiene que ir primero, antes de cualquier código: si está más abajo, se ignora y los errores siguen apareciendo.

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

Es útil mientras migras una base de código JavaScript grande, y una mala señal en cualquier otro caso.

// @ts-check hace lo contrario en un archivo JavaScript: activa la comprobación de tipos en ese archivo .js, con inferencia y tipos JSDoc, aunque checkJs esté desactivado en tsconfig.json (el archivo tiene que seguir formando parte del proyecto, mediante 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'.

En los archivos JavaScript, las etiquetas JSDoc son los tipos, y así es como muchos proyectos consiguen comprobación de tipos sin convertir los archivos a .ts.

Directivas de triple barra

Un comentario de la forma /// <reference ... /> en la primera línea de un archivo es una directiva para el compilador:

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

• types="node" añade un paquete @types al programa, como si lo pusieras en "types" de tsconfig.json.
• lib="..." añade una librería integrada al programa, como la opción lib.
• path="..." incluye otro archivo; se usa sobre todo dentro de archivos .d.ts.

En código de aplicación, las sentencias import y la configuración de tsconfig.json sustituyen casi todos sus usos; estas directivas aparecen sobre todo en archivos de declaración y en código generado, como el vite-env.d.ts de Vite. Como demostración rápida, lib hace disponible en este archivo un método de array más reciente:

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

Comentarios en la salida compilada

tsc conserva los comentarios en el JavaScript que genera. Activa "removeComments": true para quitarlos; los comentarios que empiezan por /*! sobreviven incluso así, que es la convención para las cabeceras de licencia:

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

Los comentarios JSDoc también se copian a los archivos .d.ts cuando declaration está activado, así que quienes usan una librería ven las descripciones en su editor.