TypeScript Yorum Satırları: JSDoc, @ts-ignore, @ts-expect-error

TypeScript yorumları JavaScript yorumlarıdır: satırın geri kalanı için //, bir blok için /* */. /** ile başlayan bir blok yorum bir dokümantasyon yorumudur (JSDoc); editörler onu, belgelediği şeyin üzerine geldiğinizde gösterir. Bunun yanında TypeScript, derleyicinin kodunuzu nasıl kontrol ettiğini değiştiren birkaç özel yorumu da okur.

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

Çıktı:

212

Yorumlar programı etkilemez. Aşağıda anlatılan direktif yorumları dışında tip kontrolünü de etkilemezler.

Tek Satırlık ve Blok Yorumlar

// satırda kendisinden sonraki her şeyi yoruma çevirir; bu aynı zamanda bir kod satırını devre dışı bırakmanın hızlı yoludur. /* */ bir satırın ortasında durabilir ya da çok sayıda satırı kapsayabilir.

Blok yorumlar iç içe geçmez. İlk */ yorumu bitirir, bu yüzden zaten blok yorum içeren bir kodu sarmak onu bozar:

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

Derleyici bu durumda this text is now code */ kısmını kod olarak okumaya çalışır ve bir sözdizimi hatası bildirir. Blok yorumlar içeren bir bölgeyi yoruma almak için her satırda // kullanın; çoğu editör bunu Ctrl+/ (macOS'ta Cmd+/) ile yapar.

JSDoc Dokümantasyon Yorumları

Bir fonksiyonun, sınıfın, metodun, özelliğin, interface'in veya değişkenin hemen önündeki bir /** ... */ yorumu onu belgeler. Editörler metnini üzerine gelince açılan ipucunda ve otomatik tamamlamada gösterir; TypeDoc gibi dokümantasyon üreteçleri de onu referans sayfalarına dönüştürür. TypeScript kodundaki bu yorumlar için Microsoft'un başlattığı bir standart olan TSDoc, yaygın etiketlerde aynı sözdizimini kullanır:

Bir .ts dosyasında tipleri JSDoc'ta tekrarlamayın. Tipler koddaki notasyonlardır ve JSDoc tip etiketleri orada yok sayılır: /** @type {string} */ const v: number = 5; hiçbir şikayet olmadan derlenir, çünkü yalnızca : number dikkate alınır.

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

Bir editörde, projenin herhangi bir yerinde transfer veya balance üzerine gelmek bu açıklamaları gösterir.

Kodu Kullanımdan Kaldırılmış Olarak İşaretlemek

@deprecated bir derleme hatasına yol açmaz. Editörlere, kullanımdan kaldırılan fonksiyonun her kullanımını üstü çizili ve nedeni üzerine gelince görünecek şekilde göstermelerini söyler; çağıranları bir alternatife yönlendirmenin nazik yolu budur:

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

Çıktı:

$19.99
19.99 EUR

@ts-expect-error ve @ts-ignore

Bu iki yorum, kendilerinden sonraki satırdaki tip hatalarını susturur. Bazen doğru karar budur: bir fonksiyonun hatalı girdiyi çalışma zamanında nasıl ele aldığını kontrol eden bir test ya da bir kütüphanenin tiplerindeki bilinen bir eksik.

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

Çıktı:

runtime error: text.toUpperCase is not a function

Yorum olmadan shout(42) bir derleme hatasıdır (TS2345). Yorumla birlikte dosya derlenir ve çağrı çalışma zamanına ulaşır; bu testin amacı da budur.

İki direktif arasındaki fark, hata ortadan kalktığında ortaya çıkar. @ts-expect-error susturulacak bir hata olmasında ısrar eder, bu yüzden eskimiş bir yorum kendisi bir hataya dönüşür:

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

Aynı yerdeki // @ts-ignore ise hem hata varken hem de hata gittikten sonra sessiz kalır. @ts-expect-error bu yüzden daha iyi bir varsayılandır: biri tipleri düzelttiğinde derleyici size susturmanın kaldırılabileceğini söyler. Bir sonraki okuyucu neden orada olduğunu bilsin diye, yukarıdaki örnekteki gibi direktiften sonra her zaman bir neden ekleyin.

İkisi de yalnızca sonraki satırı ve o satırdaki tüm hataları kapsar. Bir değerin tamamı için kaçış gerekiyorsa açık bir as unknown as T ya da bir çalışma zamanı kontrolü, susturma yorumundan genellikle daha anlaşılırdır.

@ts-nocheck ve @ts-check

Bir dosyanın en üstündeki // @ts-nocheck, o dosyanın tamamı için tip kontrolünü kapatır. İlk sırada, her koddan önce gelmelidir: daha aşağıya konursa yok sayılır ve hatalar yine görünür.

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

Büyük bir JavaScript kod tabanını taşırken işe yarar, başka her yerde kötü bir işarettir.

// @ts-check bir JavaScript dosyasında tersini yapar: tsconfig.json içinde checkJs kapalı olsa bile o .js dosyası için çıkarım ve JSDoc tiplerini kullanarak tip kontrolünü açar (dosyanın yine de allowJs ile projeye dahil olması gerekir):

// @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 dosyalarında JSDoc etiketleri tiplerin ta kendisidir; pek çok proje dosyaları .ts dosyasına dönüştürmeden tip kontrolünü böyle elde eder.

Triple-Slash Direktifleri

Bir dosyanın en üstündeki /// <reference ... /> biçimindeki bir yorum bir derleyici direktifidir:

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

• types="node", programa bir @types paketi ekler; tsconfig.json içindeki "types" listesine eklemek gibi.
• lib="...", programa yerleşik bir kütüphane ekler; lib seçeneği gibi.
• path="...", başka bir dosyayı dahil eder; çoğunlukla .d.ts dosyalarının içinde kullanılır.

Uygulama kodunda import ifadeleri ve tsconfig.json ayarları neredeyse her kullanımın yerini alır; bu direktiflerle çoğunlukla bildirim dosyalarında ve Vite'ın vite-env.d.ts dosyası gibi üretilmiş kodda karşılaşırsınız. Kısa bir gösterim olarak lib, bu dosyada daha yeni bir dizi metodunu kullanılabilir hale getirir:

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

Derlenmiş Çıktıdaki Yorumlar

tsc yazdığı JavaScript'te yorumları korur. Onları silmek için "removeComments": true ayarlayın; /*! ile başlayan yorumlar bu durumda bile kalır, lisans başlıkları için gelenek budur:

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

declaration açıkken JSDoc yorumları .d.ts dosyalarına da kopyalanır, böylece bir kütüphanenin kullanıcıları açıklamaları kendi editörlerinde görür.