Komentar TypeScript: JSDoc, @ts-ignore, dan @ts-expect-error

Komentar TypeScript adalah komentar JavaScript: // untuk sisa baris dan /* */ untuk blok. Komentar blok yang diawali /** adalah komentar dokumentasi (JSDoc), yang ditampilkan editor saat kursor diarahkan ke hal yang didokumentasikannya. Selain itu, TypeScript membaca beberapa komentar khusus yang mengubah cara compiler memeriksa kodemu.

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

Komentar tidak memengaruhi program. Komentar juga tidak memengaruhi pemeriksaan tipe, kecuali komentar direktif yang dibahas di bawah.

Komentar Satu Baris dan Komentar Blok

Komentar // mengubah semua yang ada setelahnya di baris itu menjadi komentar, yang juga merupakan cara cepat untuk menonaktifkan sebaris kode. /* */ bisa berada di tengah baris atau mencakup banyak baris.

Komentar blok tidak bisa bersarang. */ pertama mengakhiri komentar, jadi membungkus kode yang sudah berisi komentar blok akan merusaknya:

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

Compiler lalu mencoba membaca this text is now code */ sebagai kode dan melaporkan error sintaks. Untuk mengomentari bagian yang berisi komentar blok, pakai // di setiap baris; sebagian besar editor melakukannya dengan Ctrl+/ (Cmd+/ di macOS).

Komentar Dokumentasi JSDoc

Komentar /** ... */ tepat sebelum fungsi, class, method, property, interface, atau variabel mendokumentasikannya. Editor menampilkan teksnya di tooltip saat kursor diarahkan dan di autocomplete, dan generator dokumentasi seperti TypeDoc mengubahnya menjadi halaman referensi. TSDoc, standar untuk komentar semacam ini di kode TypeScript yang dimulai oleh Microsoft, memakai sintaks yang sama untuk tag-tag yang umum:

Di file .ts, jangan mengulang tipe di JSDoc. Anotasi di kode itulah tipenya, dan tag tipe JSDoc diabaikan di sana: /** @type {string} */ const v: number = 5; lolos kompilasi tanpa keluhan karena hanya : number yang dihitung.

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

Di editor, mengarahkan kursor ke transfer atau balance di mana pun dalam proyek akan menampilkan deskripsi ini.

Menandai Kode sebagai Usang

@deprecated tidak menyebabkan error kompilasi. Tag ini menyuruh editor menampilkan setiap pemakaian fungsi yang usang dengan coretan dan alasannya saat kursor diarahkan, cara halus untuk mengarahkan pemanggil ke penggantinya:

/** @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 dan @ts-ignore

Kedua komentar ini membungkam error tipe di baris berikutnya. Kadang itu memang pilihan yang tepat: tes yang memeriksa bagaimana sebuah fungsi menangani input yang salah saat runtime, atau celah yang sudah diketahui di tipe sebuah library.

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

Tanpa komentar itu, shout(42) adalah error kompilasi (TS2345). Dengan komentar itu, file bisa dikompilasi dan panggilannya sampai ke runtime, yang memang menjadi inti tes ini.

Perbedaan kedua direktif ini terlihat saat error-nya hilang. @ts-expect-error mewajibkan adanya error untuk dibungkam, jadi komentar yang sudah basi menjadi error itu sendiri:

// 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 di tempat yang sama tetap diam, baik selama error-nya ada maupun setelah hilang. Itulah sebabnya @ts-expect-error adalah default yang lebih baik: saat seseorang memperbaiki tipenya, compiler memberitahumu bahwa penekanan error itu bisa dihapus. Selalu tambahkan alasan setelah direktifnya, seperti contoh di atas, supaya pembaca berikutnya tahu kenapa komentar itu ada.

Keduanya hanya mencakup baris berikutnya dan semua error di baris itu. Untuk jalan pintas pada keseluruhan nilai, as unknown as T yang eksplisit atau pemeriksaan runtime biasanya lebih jelas daripada komentar pembungkam.

@ts-nocheck dan @ts-check

// @ts-nocheck di bagian atas file mematikan pemeriksaan tipe untuk seluruh file itu. Komentar ini harus berada paling depan, sebelum kode apa pun: kalau ditaruh lebih ke bawah, ia diabaikan dan error-nya tetap muncul.

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

Ini berguna saat memigrasikan codebase JavaScript yang besar, dan pertanda masalah di tempat lain.

// @ts-check melakukan kebalikannya di file JavaScript: ia menyalakan pemeriksaan tipe untuk file .js itu, memakai inferensi dan tipe JSDoc, bahkan ketika checkJs dimatikan di tsconfig.json (file itu tetap harus menjadi bagian dari proyek, lewat 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'.

Di file JavaScript, tag JSDoc adalah tipenya, dan begitulah banyak proyek mendapatkan pemeriksaan tipe tanpa mengubah file menjadi .ts.

Direktif Triple-Slash

Komentar berbentuk /// <reference ... /> di bagian paling atas file adalah direktif compiler:

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

• types="node" menambahkan package @types ke program, seperti mencantumkannya di "types" pada tsconfig.json.
• lib="..." menambahkan library bawaan ke program, seperti opsi lib.
• path="..." menyertakan file lain, kebanyakan dipakai di dalam file .d.ts.

Di kode aplikasi, pernyataan import dan pengaturan tsconfig.json menggantikan hampir semua pemakaiannya; kamu biasanya menemukan direktif ini di file deklarasi dan kode yang dihasilkan otomatis seperti vite-env.d.ts milik Vite. Sebagai demonstrasi singkat, lib membuat method array yang lebih baru tersedia di file ini:

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

Komentar di Output Hasil Kompilasi

tsc mempertahankan komentar di JavaScript yang ditulisnya. Atur "removeComments": true untuk membuangnya; komentar yang diawali /*! tetap bertahan bahkan saat itu, sesuai konvensi untuk header lisensi:

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

Komentar JSDoc juga disalin ke file .d.ts saat declaration menyala, sehingga pengguna sebuah library melihat deskripsinya di editor mereka.