وكيل المراجعة الأساسي

وكيل مراجعة التوثيق بالذكاء الاصطناعي

يحافظ على مزامنة توثيقك مع الكود

التوثيق القديم أسوأ من عدم وجود توثيق — فهو يضلل بشكل فعّال. وكيل مراجعة التوثيق يكتشف متى تجعل تغييرات الكود التوثيق خاطئًا.

ما يكتشفه مراجع التوثيق

الأخطاء الصامتة — التوثيق الذي يكذب

التوثيق القديم

توثيق يصف سلوكًا قديمًا — أخطر أنواع التوثيق

README قديمأمثلة API قديمةمعلمات ملغاة موثقة

توثيق API المفقود

دوال عامة ونقاط نهاية بدون توثيق مناسب

تصديرات غير موثقةأوصاف معلمات مفقودةلا يوجد توثيق لنوع الإرجاع

التعليقات المضللة

تعليقات تقول شيئًا بينما الكود يفعل شيئًا آخر — أسوأ من عدم وجود تعليقات

TODOs قديمةتفسيرات خاطئةتعليقات منسوخة

انحراف OpenAPI/Swagger

توثيق API لا يتطابق مع نقاط النهاية الفعلية — السبب الأول لفشل التكامل

مخطط استجابة خاطئنقاط نهاية مفقودةتوثيق مصادقة قديم

مزامنة توثيق المكونات

توثيق Storybook والمكونات الذي لا يعكس تغييرات الخصائص

خصائص مفقودةقيم افتراضية خاطئةأمثلة قديمة

عدم تطابق تعريف الأنواع

أنواع TypeDoc/JSDoc التي تكذب حول الواجهات والتوقيعات الفعلية

اختياري موسوم كمطلوبgenerics خاطئةأنواع union مفقودة

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

كل مكان يمكن أن ينفصل فيه التوثيق عن الكود

JSDoc / TSDoc

توثيق الدوال والأساليب

ملفات README

نظرة عامة على المشروع والحزم

التعليقات المضمنة

شروحات الكود و TODOs

توثيق API

أوصاف نقاط النهاية والأمثلة

تعريفات الأنواع

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

إدخالات سجل التغييرات

دقة تاريخ الإصدارات

مقياس فريد

نقاط دين التوثيق

تمامًا مثل الدين التقني، يتراكم دين التوثيق بصمت. نمنح قاعدة الكود الخاصة بك نقاط صحة التوثيق — رقم واحد يوضح مدى انحراف توثيقك عن الواقع.

تتبع حداثة التوثيق بمرور الوقت
تحديد الملفات التي تغيرت بدون تحديث التوثيق
تحديد أولويات ما يجب إصلاحه أولاً

صحة التوثيق

73/100

README.md

آخر تحديث قبل 45 يومًا، تم تغيير الكود 12 مرة منذ ذلك الحين

src/api/

3 نقاط نهاية غير موثقة

CHANGELOG.md

إدخالات مفقودة للإصدارات v2.3.0، v2.3.1

src/utils/

8 دوال مصدرة بدون JSDoc

الاتجاه هذا الشهر-5 نقاط
مدرك للإطار

معرفة عميقة بالأطر

ليس مجرد فحوصات توثيق عامة — نحن نفهم أنماط توثيق إطار العمل الخاص بك

Next.js / React

  • توثيق خصائص المكونات
  • أمثلة استخدام الخطافات
  • أوصاف معالجات المسارات
  • توثيق البرمجيات الوسيطة

NestJS / Express

  • مزامنة مزخرفات Swagger
  • توثيق DTO
  • توثيق أساليب المتحكم
  • أوصاف الوحدات

FastAPI / Django

  • سلاسل توثيق نماذج Pydantic
  • أوصاف نقاط النهاية
  • مخططات الاستجابة
  • توثيق معلمات الاستعلام

GraphQL

  • أوصاف المخطط
  • توثيق المحللات
  • تعريفات الأنواع
  • توثيق الطفرات/الاستعلامات
اقتراح الذكاء الاصطناعي

للدالة processPayment(amount, currency, options):

/**
 * Processes a payment transaction
 * @param amount - Payment amount in cents (integer)
 * @param currency - ISO 4217 currency code
 * @param options - Processing options
 * @param options.idempotencyKey - Unique key
 * @param options.metadata - Custom key-value pairs
 * @returns Promise<PaymentResult>
 * @throws PaymentError if declined
 */
مدعوم بالذكاء الاصطناعي

ليس فقط الكشف — بل التوليد

عندما نجد توثيقًا مفقودًا أو قديمًا، لا نبلغ عنه فقط — نحن نولّد الإصلاح. يحلل الذكاء الاصطناعي توقيعات الدوال وأنواع الإرجاع وأنماط الاستخدام لاقتراح توثيق دقيق.

توليد JSDoc تلقائيًا

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

تحديث التوثيق الموجود

يصحح التوثيق القديم ليتطابق مع الكود الحالي

اكتشاف انحراف التوثيق

أمثلة حقيقية على توثيق يحتاج إلى تحديث

توثيق معلمات قديم

قديم
/**
 * Fetches user by ID
 * @param id - User ID
 * @param includeDeleted - Include soft-deleted users
 */
async function getUser(id: string, options?: GetUserOptions) {
  // includeDeleted moved to options object 3 months ago
  // but JSDoc still shows old signature
}

JSDoc يعرض توقيعًا قديمًا مع معلمة موضعية

محدّث
/**
 * Fetches user by ID
 * @param id - User ID
 * @param options - Query options
 * @param options.includeDeleted - Include soft-deleted users
 * @param options.fields - Fields to select
 */
async function getUser(id: string, options?: GetUserOptions) {
  // Documentation matches actual signature
}

التحديث ليتطابق مع نمط كائن الخيارات الحالي

تعليق مضلل

قديم
// Retry 3 times with exponential backoff
async function fetchWithRetry(url: string) {
  const MAX_RETRIES = 5  // Changed from 3
  const response = await fetch(url)
  // Actually no retry logic implemented anymore
  return response
}

التعليق يصف منطق إعادة المحاولة غير الموجود

محدّث
// Simple fetch wrapper, no retry logic
// For retries, use fetchWithRetry from @/lib/http
async function simpleFetch(url: string) {
  const response = await fetch(url)
  return response
}

التعليق يعكس السلوك الفعلي

انحراف README

قديم
## Installation
```bash
npm install
npm run setup  # This script was removed
```

## Environment Variables
- `DATABASE_URL` - PostgreSQL connection
- `REDIS_URL` - Redis connection  # We switched to in-memory cache

README يشير إلى سكربت محذوف وإعداد Redis قديم

محدّث
## Installation
```bash
npm install
```

## Environment Variables
- `DATABASE_URL` - PostgreSQL connection string
- `CACHE_TTL` - Cache duration in seconds (default: 3600)

التوثيق يعكس عملية الإعداد الحالية

التحليل الدلالي

كيف يعمل مراجع التوثيق

مراجع التوثيق لا يتحقق فقط من وجود التوثيق — بل يتحقق من تطابقه مع ما يفعله الكود فعليًا. عندما تغير توقيع دالة، يشير إلى JSDoc.

المطابقة الدلالية

يقارن ما يقوله التوثيق مع ما يفعله الكود

اكتشاف التغييرات

يلاحظ متى تبطل تغييرات الكود التوثيق القريب

اقتراحات التحديث

يوفر نصًا محددًا لإصلاح التوثيق

خط أنابيب التحليل

1

مقارنة الكود والتوثيق

يتحقق مما إذا كان التوثيق يتطابق مع التنفيذ الفعلي

2

اكتشاف التغييرات

يحدد متى تبطل تغييرات الكود التوثيق الموجود

3

الإبلاغ عن عدم التطابق

يبلغ عن التوثيق الذي قد يضلل المطورين

4

اقتراح التحديثات

يوفر نصًا محددًا لتحديث التوثيق

لماذا تهم دقة التوثيق

التوثيق السيئ يكلف أكثر من عدم وجود توثيق

تصحيح أسرع

التوثيق الدقيق يعني أن المطورين لا يضيعون ساعات في ملاحقة مسارات خاطئة

تأهيل أفضل

يمكن للمطورين الجدد الوثوق بما يقرأونه بدلاً من التخمين

ثقة API

يمكن للمستخدمين الاعتماد على توثيق API الخاص بك بدون التجربة والخطأ

كل تغيير في الكود هو فرصة لانحراف التوثيق.
مراجع التوثيق يكتشفه في كل مرة.

دين التوثيق في كل مكان

هذه المشاكل تتسلل يوميًا — حتى الآن

65%

من ملفات README تصبح قديمة خلال 6 أشهر

40%

من تعليقات JSDoc لا تتطابق مع توقيعات الدوال

3.2 س

متوسط الوقت الضائع في التصحيح بسبب التوثيق الخاطئ

80%

من توثيق API يفتقد حقلًا مطلوبًا واحدًا على الأقل

حافظ على مزامنة التوثيق والكود

دع مراجع التوثيق يكتشف الانحراف قبل أن يضلل. مجاني لمدة 14 يومًا، لا حاجة لبطاقة ائتمان.

التحقق من JSDoc
مزامنة README
دقة التعليقات