הערות ב-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

הערות לא משפיעות על התוכנית. הן גם לא משפיעות על בדיקת הטיפוסים, חוץ מהערות ההנחיה שמוסברות בהמשך.

הערות של שורה אחת והערות בלוק

// הופך להערה את כל מה שאחריו בשורה, וזו גם הדרך המהירה לנטרל שורת קוד. /* */ יכול לשבת באמצע שורה או לכסות הרבה שורות.

הערות בלוק לא מקוננות. ה-*/ הראשון מסיים את ההערה, ולכן עטיפה של קוד שכבר מכיל הערת בלוק נשברת:

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

אז הקומפיילר מנסה לקרוא את this text is now code */ כקוד ומדווח על שגיאת תחביר. כדי להפוך להערה אזור שמכיל הערות בלוק, השתמשו ב-// בכל שורה; רוב העורכים עושים את זה עם Ctrl+/ (Cmd+/ ב-macOS).

הערות תיעוד JSDoc

הערת /** ... */ מיד לפני פונקציה, מחלקה, מתודה, מאפיין, interface או משתנה מתעדת אותם. עורכים מציגים את הטקסט שלה בחלונית הריחוף ובהשלמה האוטומטית, וכלים ליצירת תיעוד כמו TypeDoc הופכים אותה לעמודי עיון. TSDoc, תקן להערות האלה בקוד TypeScript שהתחיל ב-Microsoft, משתמש באותו תחביר לתגיות הנפוצות:

בקובץ .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

שתי ההערות האלה משתיקות שגיאות טיפוסים בשורה שאחריהן. לפעמים זו ההחלטה הנכונה: בדיקה שבודקת איך פונקציה מטפלת בקלט שגוי בזמן ריצה, או פער ידוע בטיפוסים של ספרייה.

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). איתה, הקובץ עובר קומפילציה והקריאה מגיעה לזמן הריצה, וזו כל המטרה של הבדיקה הזו.

ההבדל בין שתי ההנחיות מתגלה כשהשגיאה נעלמת. @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 היא ברירת המחדל הטובה יותר: כשמישהו מתקן את הטיפוסים, הקומפיילר אומר לכם שאפשר להסיר את ההשתקה. תמיד הוסיפו סיבה אחרי ההנחיה, כמו בדוגמה למעלה, כדי שהקורא הבא יידע למה היא שם.

שתיהן מכסות רק את השורה הבאה ואת כל השגיאות בה. כשצריך לעקוף ערך שלם, 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: היא מפעילה בדיקת טיפוסים לקובץ ה-.js הזה, בעזרת הסקה וטיפוסי JSDoc, גם כש-checkJs כבוי ב-tsconfig.json (הקובץ עדיין צריך להיות חלק מהפרויקט, דרך 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.

הנחיות Triple-Slash

הערה מהצורה /// <reference ... /> ממש בראש קובץ היא הנחיה לקומפיילר:

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

• types="node" מוסיפה חבילת @types לתוכנית, כמו רישום שלה ב-"types" ב-tsconfig.json.
• lib="..." מוסיפה ספרייה מובנית לתוכנית, כמו האפשרות lib.
• path="..." כוללת קובץ אחר, בעיקר בתוך קבצי .d.ts.

בקוד של אפליקציה, פקודות import והגדרות ב-tsconfig.json מחליפות כמעט כל שימוש; בדרך כלל פוגשים את ההנחיות האלה בקבצי הצהרה ובקוד שנוצר אוטומטית, כמו vite-env.d.ts של Vite. כהדגמה מהירה, 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 */

הערות JSDoc מועתקות גם לקבצי .d.ts כש-declaration פעיל, וכך משתמשים בספרייה רואים את התיאורים בעורך שלהם.