التعليقات في 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

تعليق /** ... */ الموضوع مباشرة قبل دالة أو صنف أو method أو خاصية أو 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.

توجيهات الشرطات الثلاث

التعليق من الشكل /// <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، فيرى مستخدمو المكتبة الأوصاف في محرراتهم.