Comentários em TypeScript: JSDoc, @ts-ignore e @ts-expect-error

Os comentários do TypeScript são comentários do JavaScript: // para o resto de uma linha e /* */ para um bloco. Um comentário de bloco que começa com /** é um comentário de documentação (JSDoc), que os editores mostram quando você passa o mouse sobre aquilo que ele documenta. Além disso, o TypeScript lê alguns comentários especiais que mudam como o compilador verifica o seu 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

Saída:

212

Comentários não afetam o programa. Também não afetam a verificação de tipos, com exceção dos comentários de diretiva vistos mais abaixo.

Comentários de uma linha e de bloco

// comenta tudo o que vem depois dele na linha, e é também o jeito rápido de desativar uma linha de código. /* */ pode ficar no meio de uma linha ou cobrir várias linhas.

Comentários de bloco não se aninham. O primeiro */ encerra o comentário, então envolver código que já contém um comentário de bloco quebra:

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

O compilador tenta então ler this text is now code */ como código e aponta um erro de sintaxe. Para comentar uma região que contém comentários de bloco, use // em cada linha; a maioria dos editores faz isso com Ctrl+/ (Cmd+/ no macOS).

Comentários de documentação JSDoc

Um comentário /** ... */ logo antes de uma função, classe, método, propriedade, interface ou variável a documenta. Os editores mostram o texto dele no tooltip e no autocompletar, e geradores de documentação como o TypeDoc o transformam em páginas de referência. O TSDoc, um padrão para esses comentários em código TypeScript criado pela Microsoft, usa a mesma sintaxe para as tags comuns:

Em um arquivo .ts, não repita os tipos no JSDoc. As anotações no código são os tipos, e as tags de tipo JSDoc são ignoradas ali: /** @type {string} */ const v: number = 5; compila sem reclamação, porque só o : number conta.

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

Em um editor, passar o mouse sobre transfer ou balance em qualquer lugar do projeto mostra essas descrições.

Marcando código como obsoleto

@deprecated não causa erro de compilação. Ele diz aos editores para mostrar todo uso da função obsoleta riscado e com o motivo ao passar o mouse, o que é o jeito suave de levar quem chama para um substituto:

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

Saída:

$19.99
19.99 EUR

@ts-expect-error e @ts-ignore

Esses dois comentários silenciam os erros de tipo da linha seguinte. Às vezes é a decisão certa: um teste que verifica como uma função lida com entrada inválida em tempo de execução, ou uma falha conhecida nos tipos de uma biblioteca.

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

Saída:

runtime error: text.toUpperCase is not a function

Sem o comentário, shout(42) é um erro de compilação (TS2345). Com ele, o arquivo compila e a chamada chega ao tempo de execução, que é o objetivo desse teste.

A diferença entre as duas diretivas aparece quando o erro some. @ts-expect-error exige que haja um erro para suprimir, então um comentário esquecido vira ele mesmo um erro:

// 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 no mesmo lugar fica em silêncio, tanto enquanto o erro existe quanto depois que ele some. Por isso @ts-expect-error é o melhor padrão: quando alguém corrige os tipos, o compilador avisa que a supressão pode sair. Sempre escreva um motivo depois da diretiva, como no exemplo acima, para que o próximo leitor saiba por que ela está ali.

As duas só cobrem a linha seguinte e todos os erros dela. Para escapar do sistema de tipos com um valor inteiro, um as unknown as T explícito ou uma verificação em tempo de execução costuma ser mais claro que um comentário de supressão.

@ts-nocheck e @ts-check

// @ts-nocheck no topo de um arquivo desliga a verificação de tipos do arquivo inteiro. Ele precisa vir primeiro, antes de qualquer código: colocado mais abaixo, é ignorado e os erros continuam aparecendo.

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

É útil durante a migração de uma base de código JavaScript grande, e um mau sinal em qualquer outro lugar.

// @ts-check faz o contrário em um arquivo JavaScript: liga a verificação de tipos daquele arquivo .js, usando inferência e tipos JSDoc, mesmo com checkJs desligado no tsconfig.json (o arquivo ainda precisa fazer parte do projeto, 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'.

Em arquivos JavaScript as tags JSDoc são os tipos, e é assim que muitos projetos têm verificação de tipos sem converter arquivos para .ts.

Diretivas de barra tripla

Um comentário no formato /// <reference ... /> bem no topo de um arquivo é uma diretiva do compilador:

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

• types="node" adiciona um pacote @types ao programa, como listá-lo em "types" no tsconfig.json.
• lib="..." adiciona uma biblioteca nativa ao programa, como a opção lib.
• path="..." inclui outro arquivo, usado principalmente dentro de arquivos .d.ts.

No código de aplicações, instruções import e configurações do tsconfig.json substituem quase todos os usos; você encontra essas diretivas principalmente em arquivos de declaração e em código gerado, como o vite-env.d.ts do Vite. Como demonstração rápida, lib disponibiliza um método de array mais novo neste arquivo:

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

Comentários na saída compilada

O tsc mantém os comentários no JavaScript que grava. Defina "removeComments": true para descartá-los; comentários que começam com /*! sobrevivem mesmo assim, que é a convenção para cabeçalhos de licença:

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

Comentários JSDoc também são copiados para os arquivos .d.ts quando declaration está ligado, então quem usa uma biblioteca vê as descrições no editor.