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

مقدمة: لماذا نحتاج إلى التوثيق في مشاريع TypeScript

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

الأساسيات: JSDoc والشروح التوضيحية لـ TypeScript

يدعم TypeScript بناء جملة JSDoc، مما يسمح بإضافة تعليقات منظمة مباشرة في الكود. هذا هو الأساس لإنشاء توثيق مفهوم لكل من الإنسان والأدوات.

وسوم JSDoc الأساسية

لنبدأ بمثال بسيط لدالة تجمع رقمين:

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

الوسوم الرئيسية:

\n
• @param — يصف وسيط الدالة. يُوصى بتحديد النوع والغرض.
\n
• @returns — يصف القيمة المُرجعة.
\n
• @throws — يحدد الاستثناءات التي قد تطرحها الدالة.
\n
• @example — يعرض مثالاً على الاستخدام.
\n

توثيق الأنواع المعقدة

بالنسبة للواجهات والأنواع، استخدم @property أو قم بوصف الحقول داخل الكتلة:

interface UserConfig {\n    /** اسم المستخدم */\n    name: string;\n    /** عمر المستخدم (اختياري) */\n    age?: number;\n    /** الدور في النظام */\n    role: 'admin' | 'user';\n}\n\n/**\n * ينشئ تكوين مستخدم.\n * @param config - كائن بإعدادات المستخدم.\n * @returns كائن التكوين.\n */\nfunction createUser(config: UserConfig): UserConfig {\n    return config;\n}

استخدم @template للأنواع العامة (Generics):

/**\n * غلاف لتخزين قيمة.\n * @template T - نوع القيمة المخزنة.\n */\nclass Box<T> {\n    /** القيمة المخزنة */\n    value: T;\n    constructor(value: T) {\n        this.value = value;\n    }\n}

أدوات توليد التوثيق: TypeDoc

TypeDoc هي الأداة الرئيسية للتوليد التلقائي للتوثيق من شروح JSDoc في TypeScript. تقوم بإنشاء موقع HTML ثابت مع تنقل سهل.

التثبيت والإعداد

قم بتثبيت TypeDoc كتبعية تطوير (dev-dependency):

npm install --save-dev typedoc

أنشئ ملف الإعداد typedoc.json في جذر المشروع:

{\n  "entryPoints": ["src/index.ts"],\n  "out": "docs",\n  "theme": "default",\n  "excludePrivate": true,\n  "excludeProtected": false,\n  "includeVersion": true,\n  "categorizeByGroup": true\n}

معلمات الإعداد:

\n
• entryPoints — نقطة الدخول إلى مشروعك (عادةً ملف التصدير الرئيسي).
\n
• out — المجلد الذي سيتم توليد التوثيق فيه.
\n
• excludePrivate — إخفاء الأعضاء الخاصين في الفئات.
\n
• includeVersion — إضافة إصدار المشروع إلى التوثيق.
\n

تشغيل التوليد

أضف سكريبت إلى package.json:

{\n  "scripts": {\n    "docs:generate": "typedoc"\n  }\n}

نفذ الأمر:

npm run docs:generate

بعد ذلك، سيظهر موقع ثابت في مجلد docs. افتح docs/index.html في المتصفح.

أفضل الممارسات لكتابة التوثيق

لكي يكون التوثيق مفيداً، اتبع بعض القواعد.

1. اكتب التعليقات