TypeDoc TypeScript: دليل شامل، أمثلة، تثبيت

ما هو TypeDoc ولماذا تحتاجه؟

TypeDoc هو أداة قوية لتوليد التوثيق التلقائي لمشاريع TypeScript. يقوم بإنشاء صفحات HTML جميلة ومنظمة بناءً على التعليقات التي تكتبها في الكود بصيغة JSDoc. إذا سبق لك كتابة كود TypeScript وأردت الحصول على توثيق يشبه التوثيق الرسمي لـ TypeScript أو المكتبات الشهيرة، فإن TypeDoc هو الحل الأمثل.

لماذا تحتاجه؟ في التطوير الحديث، التوثيق ليس رفاهية بل ضرورة. TypeDoc يحل عدة مشاكل رئيسية:

الأتمتة: لست بحاجة لكتابة التوثيق يدويًا. فقط أضف تعليقات للدوال والكلاسات والواجهات والأنواع، وسيقوم TypeDoc بإنشاء موقع توثيق كامل.
المواكبة: التوثيق دائمًا محدث ومتوافق مع الكود، لأنه يُنشأ مباشرة منه.
التنقل: يوفر TypeDoc تنقلًا سهلًا في المشروع: هيكل شجري، بحث، وروابط للأنواع.
دعم TypeScript: يفهم الأنواع المعقدة في TypeScript مثل الأنواع العامة (Generics)، والأنواع المساعدة (Utility Types)، وتحميل الدوال (Function Overloads)، والوحدات (Modules)، والمساحات الاسمية (Namespaces).
قابلية التوسع: يدعم TypeDoc السمات (Themes)، والإضافات (Plugins)، والتخصيص.

TypeDoc مثالي لـ:

المكتبات والحزم المنشورة عبر npm.
المشاريع الداخلية التي تحتاج لتعريف المطورين الجدد بالكود بسرعة.
توثيق API لتطبيقات الخادم المكتوبة بـ TypeScript.
المشاريع التعليمية التي تتطلب وضوحًا بصريًا.

تثبيت TypeDoc

يتم تثبيت TypeDoc عبر npm (Node Package Manager). تأكد من تثبيت Node.js (الإصدار 14 أو أحدث).

الطريقة الأسهل هي تثبيت TypeDoc بشكل عام (Globally):

npm install -g typedoc

ولكن يُنصح للمشاريع بتثبيته كتبعية تطوير محلية:

npm install --save-dev typedoc

بعد التثبيت، يمكنك التحقق من الإصدار:

npx typedoc --version

إذا كنت تستخدم Yarn:

yarn add -D typedoc

أو لـ pnpm:

pnpm add -D typedoc

بداية سريعة مع مثال برمجي

لنقم بإنشاء مشروع بسيط وتوليد توثيق له.

الخطوة 1: إنشاء المشروع

mkdir my-typedoc-project
cd my-typedoc-project
npm init -y

الخطوة 2: تثبيت TypeDoc

npm install --save-dev typedoc

الخطوة 3: إنشاء ملف الكود src/index.ts

/**
 * وحدة للعمليات الرياضية.
 * @module MathUtils
 */

/**
 * يجمع رقمين.
 * @param a - الرقم الأول
 * @param b - الرقم الثاني
 * @returns مجموع a و b
 * @example
 * ```typescript
 * const result = add(2, 3);
 * console.log(result); // 5
 * ```
 */
export function add(a: number, b: number): number {
    return a + b;
}

/**
 * يطرح الرقم الثاني من الأول.
 * @param a - المطروح منه
 * @param b - المطروح
 * @returns الفرق بين a و b
 */
export function subtract(a: number, b: number): number {
    return a - b;
}

/**
 * واجهة لتمثيل نقطة في الفضاء ثنائي الأبعاد.
 */
export interface Point {
    /** إحداثي X */
    x: number;
    /** إحداثي Y */
    y: number;
}

/**
 * يحسب المسافة بين نقطتين.
 * @param p1 - النقطة الأولى
 * @param p2 - النقطة الثانية
 * @returns المسافة بين النقطتين
 */
export function distance(p1: Point, p2: Point): number {
    const dx = p2.x - p1.x;
    const dy = p2.y - p1.y;
    return Math.sqrt(dx * dx + dy * dy);
}

الخطوة 4: توليد التوثيق