توثيق TypeScript: كيفية كتابة كود يتحدث عن نفسه

مقدمة: لماذا التوثيق ليس واجبًا مملًا، بل قوة خارقة

تخيل: تعود إلى مشروعك بعد ستة أشهر. تفتح ملف منطق تسجيل الدخول - وترى بحرًا من كود TypeScript. الأنواع موجودة، والواجهات محددة، لكن ما الذي تفعله هذه الدالة؟ لماذا يُسمى المُعامل opts وما هي حقوله؟ هل يبدو الأمر مألوفًا؟

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

1. JSDoc و TSDoc: أساس توثيقك

ورث TypeScript من JavaScript تنسيق JSDoc الشائع، ثم طور المجتمع TSDoc - وهو بناء جملة موحد لـ TypeScript. إذا كنت تكتب مكتبة أو API، فإن TSDoc هو خيارك الأمثل. إنه أكثر صرامة، ويتكامل بشكل أفضل مع المحررات وأدوات إنشاء التوثيق.

الوسوم الأساسية في TSDoc

إليك الحد الأدنى الذي يجب أن يعرفه كل مطور:

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

/**\n * تحسب الخصم على المنتج مع مراعاة الكود الترويجي.\n * \n * @param price - السعر الأصلي للمنتج (يجب أن يكون أكبر من 0)\n * @param discountPercent - نسبة الخصم (من 0 إلى 100)\n * @param promoCode - الكود الترويجي الذي قد يزيد الخصم\n * @returns السعر النهائي بعد تطبيق الخصم\n * @throws {Error} إذا كان السعر أو النسبة غير صحيحين\n * \n * @example\n * // مثال: خصم 20% على منتج سعره 1000 روبل\n * const finalPrice = calculateDiscount(1000, 20, 'SUMMER');\n * console.log(finalPrice); // 800\n */\nfunction calculateDiscount(\n  price: number,\n  discountPercent: number,\n  promoCode?: string\n): number {\n  if (price <= 0 || discountPercent < 0 || discountPercent > 100) {\n    throw new Error('معاملات غير صحيحة');\n  }\n  \n  let discount = discountPercent;\n  if (promoCode === 'SUMMER') {\n    discount += 10; // خصم إضافي\n  }\n  \n  return price * (1 - discount / 100);\n}\n

نصيحة: قم دائمًا بوصف الحالات الحدودية. إذا كان المُعامل قد يكون undefined، فاذكر ذلك في الوصف. أنواع TypeScript جيدة، لكن اللغة البشرية تضيف سياقًا.

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

واحدة من أهم ميزات TypeScript هي نظام الأنواع القوي. لكن حتى النوع الأكثر صرامة لن يشرح الغرض من الحقل. قم بتوثيق الواجهات بنفس دقة توثيق الدوال.

/**\n * إعدادات الاتصال بـ API الطقس الخارجي.\n */\ninterface WeatherApiConfig {\n  /** عنوان URL الأساسي لـ API (مثل: https://api.weather.com) */\n  baseUrl: string;\n  \n  /** مفتاح المصادقة الذي تم الحصول عليه من المزود */\n  apiKey: string;\n  \n  /** \n   * عدد الثواني لانتظار الرد من الخادم.\n   * القيمة الافتراضية هي 5 ثوانٍ.\n   */\n  timeout?: number;\n  \n  /**\n   * إصدار API. إذا لم يتم تحديده، يتم استخدام أحدث إصدار مستقر.\n   * @deprecated استخدم حقل `version` في عنوان URL\n   */\n  apiVersion?: string;\n}\n

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

3. إنشاء التوثيق: تحويل التعليقات إلى موقع

كتابة التعليقات هي نصف المهمة. يجب أن تكون قادرًا على تحويلها إلى توثيق سهل الاستخدام. بالنسبة لـ TypeScript، أفضل أداة هي TypeDoc. فهو يحلل تعليقات TSDoc الخاصة بك