كتابة توثيق لمشروع TypeScript: من الألف إلى الياء

مقدمة: لماذا التوثيق استثمار وليس مضيعة للوقت

كل مطور واجه موقفًا: عند العودة إلى الكود الخاص به بعد شهر، يجد صعوبة في تذكر سبب وجود معلمة معينة. ناهيك عن أعضاء الفريق الجدد الذين يحاولون فهم مشروعك. التوثيق عالي الجودة لمشروع TypeScript ليس مجرد إضافة لطيفة، بل عنصر حاسم يسرّع عملية الانضمام للفريق، ويقلل عدد الأخطاء، ويجعل الكود قابلًا للصيانة.

TypeScript، كونه طبقة فوق JavaScript، يوفر نظام أنواع قوي. لكن الأنواع وحدها لا تجيب دائمًا على سؤال "لماذا". التوثيق يسد هذه الفجوة. في هذه المقالة، سنغطي الدورة الكاملة: من اختيار أسلوب التعليقات إلى إنشاء موقع ثابت للتوثيق.

1. الأساسيات: JSDoc وTSDoc وTypeScript

لتوثيق كود TypeScript، تطور معياران رئيسيان تاريخيًا: JSDoc وTSDoc. JSDoc هو التنسيق القديم الجيد الذي جاء من عالم JavaScript. TSDoc هو معيار أكثر حداثة، محسّن خصيصًا لـ TypeScript. كلا الأسلوبين يستخدمان تعليقات بتنسيق /** ... */.

لنلقِ نظرة على مثال أساسي باستخدام JSDoc:

/** * يحسب مجموع رقمين. * @param a - الرقم الأول * @param b - الرقم الثاني * @returns مجموع a و b */function add(a: number, b: number): number {    return a + b;}

وهذا هو الشكل نفسه بأسلوب TSDoc باستخدام الوسوم @param و @returns:

/** * يحسب مجموع رقمين. * @param a - الرقم الأول * @param b - الرقم الثاني * @returns مجموع a و b */function add(a: number, b: number): number {    return a + b;}

الفرق ضئيل، لكن TSDoc يضيف دعمًا للهياكل الخاصة بـ TypeScript مثل الأنواع العامة (Generics) والأنواع الشرطية.

1.1 توثيق الواجهات والأنواع

يجب إيلاء اهتمام خاص للواجهات والأنواع. فهي "الهيكل العظمي" لمشروع TypeScript. إليك مثال لواجهة موثقة جيدًا:

/** * يمثل مستخدم النظام. */interface User {    /** معرف المستخدم الفريد */    id: string;    /** الاسم الكامل للمستخدم */    name: string;    /** عنوان البريد الإلكتروني (يجب أن يكون فريدًا) */    email: string;    /** تاريخ آخر تسجيل دخول (اختياري) */    lastLogin?: Date;    /** دور المستخدم في النظام */    role: 'admin' | 'user' | 'moderator';}

لاحظ: كل معلمة في الواجهة لها تعليق /** ... */ خاص بها. هذا يسمح لبيئة التطوير المتكاملة (IDE) (مثل VS Code) بعرض تلميحات عند استخدام هذه الواجهة.

2. تقنيات متقدمة: الأنواع العامة والأنواع الشرطية

يشتهر TypeScript بنظام الأنواع الخاص به، ويجب أن يعكس التوثيق تعقيده. هذا ينطبق بشكل خاص على الأنواع العامة (generic types) والأنواع الشرطية (conditional types).

لنلقِ نظرة على مثال لنوع عام مع توثيق:

/** * ينشئ مصفوفة من عنصر واحد من النوع T. * @template T - نوع العنصر الذي سيتم وضعه في المصفوفة * @param item - العنصر المراد تغليفه * @returns مصفوفة تحتوي على العنصر المُمرر */function wrapInArray<T>(item: T): T[] {    return [item];}

الوسم @template يحدد بوضوح ما هو T. هذا مفيد بشكل خاص عندما يكون هناك عدة أنواع عامة أو عندما تكون لها علاقات معقدة.

بالنسبة للأنواع الشرطية، يصبح التوثيق أكثر أهمية. مثال:

/** * يستخرج نوع القيمة من Promise، إذا تم تمرير Promise. * وإلا يُرجع النوع الأصلي. * @template T - النوع الذي قد يكون Promise أو لا * @example * // بالنسبة لـ Promise<number> سيعيد number * type Result = UnwrapPromise<Promise<number>>; // number