TypeScriptのコメント: JSDoc、@ts-ignore、@ts-expect-error

TypeScriptのコメントはJavaScriptのコメントと同じです。行の残りには //、ブロックには /* */ を使います。/** で始まるブロックコメントはドキュメンテーションコメント（JSDoc）で、説明の対象にカーソルを合わせるとエディターに表示されます。さらにTypeScriptは、コンパイラーのチェック方法を変えるいくつかの特別なコメントを読み取ります。

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

出力:

212

コメントはプログラムの動作に影響しません。後で説明するディレクティブコメントを除けば、型チェックにも影響しません。

1行コメントとブロックコメント

// はその行のそれ以降をすべてコメントにします。コードの1行を手早く無効にする方法でもあります。/* */ は行の途中に置くことも、複数行を囲むこともできます。

ブロックコメントは入れ子にできません。最初の */ でコメントが終わるので、すでにブロックコメントを含むコードを囲むと壊れます。

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

するとコンパイラーは this text is now code */ をコードとして読もうとし、構文エラーを報告します。ブロックコメントを含む範囲をコメントアウトするには、各行に // を付けます。ほとんどのエディターではCtrl+/（macOSではCmd+/）でできます。

JSDocのドキュメンテーションコメント

関数、クラス、メソッド、プロパティ、インターフェース、変数の直前に置いた /** ... */ コメントは、その説明になります。エディターはその内容をホバーのツールチップや補完に表示し、TypeDocのようなドキュメント生成ツールはリファレンスページに変換します。Microsoftが始めた、TypeScriptのコード向けのこうしたコメントの標準であるTSDocも、よく使うタグは同じ構文です。

.ts ファイルでは、JSDocに型を繰り返し書かないでください。コードの型注釈が型であり、そこではJSDocの型タグは無視されます。/** @type {string} */ const v: number = 5; は何のエラーもなくコンパイルされます。有効なのは : 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

エディターでは、プロジェクトのどこでも transfer や balance にカーソルを合わせると、これらの説明が表示されます。

コードを非推奨にする

@deprecated はコンパイルエラーにはなりません。エディターに対して、非推奨の関数を使っている箇所をすべて取り消し線付きで表示し、ホバーで理由を示すよう伝えます。呼び出し側を代わりの関数へ穏やかに誘導する方法です。

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

出力:

$19.99
19.99 EUR

@ts-expect-errorと@ts-ignore

この2つのコメントは、次の行の型エラーを抑制します。それが正しい判断になることもあります。たとえば、関数が実行時に不正な入力をどう扱うかを確かめるテストや、ライブラリの型にわかっている不備がある場合です。

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

出力:

runtime error: text.toUpperCase is not a function

コメントがなければ、shout(42) はコンパイルエラー（TS2345）です。コメントがあればファイルはコンパイルされ、呼び出しが実行時まで届きます。それがこのテストの目的です。

2つのディレクティブの違いは、エラーがなくなったときに現れます。@ts-expect-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 は、エラーがある間もなくなったあとも黙ったままです。だからこそ @ts-expect-error のほうが基本として優れています。誰かが型を直したとき、抑制を削除してよいことをコンパイラーが教えてくれるからです。上の例のように、ディレクティブのあとには必ず理由を書き、次に読む人がなぜそこにあるのかわかるようにしましょう。

どちらも次の1行と、その行のすべてのエラーだけが対象です。値全体を型チェックから外すなら、抑制コメントより、明示的な as unknown as T や実行時のチェックのほうがたいていわかりやすくなります。

@ts-nocheckと@ts-check

ファイルの先頭の // @ts-nocheck は、そのファイル全体の型チェックを無効にします。コードより前、最初に書く必要があります。それより下に置くと無視され、エラーは表示されたままです。

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

大きなJavaScriptのコードベースを移行している間は便利ですが、それ以外の場所で使うのは悪い兆候です。

// @ts-check はJavaScriptファイルで逆の働きをします。tsconfig.json で checkJs が無効でも、その .js ファイルについて、推論とJSDocの型を使った型チェックを有効にします（ファイルは 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'.

JavaScriptファイルでは、JSDocのタグそのものが型です。多くのプロジェクトは、こうしてファイルを .ts に変換せずに型チェックを取り入れています。

トリプルスラッシュ・ディレクティブ

ファイルの一番上にある /// <reference ... /> という形のコメントは、コンパイラーへのディレクティブです。

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

• types="node" は、tsconfig.json の "types" に書くのと同じように、@types パッケージをプログラムに追加します。
• lib="..." は、lib オプションと同じように、組み込みライブラリをプログラムに追加します。
• path="..." は別のファイルを取り込みます。主に .d.ts ファイルの中で使われます。

アプリケーションのコードでは、ほとんどの用途が import 文と tsconfig.json の設定に置き換わっています。このディレクティブを目にするのは、主に宣言ファイルや、Viteの vite-env.d.ts のような生成されたコードです。簡単な例として、lib を使うとこのファイルで新しい配列メソッドが使えるようになります。

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

コンパイル後の出力に残るコメント

tsc は書き出すJavaScriptにコメントを残します。削除するには "removeComments": true を設定します。その場合でも /*! で始まるコメントは残ります。これはライセンスヘッダーの慣習です。

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

declaration が有効なら、JSDocコメントは .d.ts ファイルにもコピーされるので、ライブラリの利用者はエディターで説明を見ることができます。