ورقة غش توثيق JSDoc 3

JSDoc هي أداة لتوليد وثائق واجهات برمجة التطبيقات وصيغة لتوضيح الأنواع في JavaScript، وتدعمها خوادم لغة TypeScript.

توثيق الدوال

/**
 * Calculates total invoice sum including tax.
 *
 * @param {number} subtotal - Net amount before tax.
 * @param {number} [taxRate=0.1] - Optional tax percentage (defaults to 10%).
 * @param {string} [currency='USD'] - Three-letter ISO currency code.
 * @returns {number} The calculated total invoice price.
 * @throws {RangeError} When subtotal is negative.
 */
function calculateTotal(subtotal, taxRate = 0.1, currency = 'USD') {
  if (subtotal < 0) throw new RangeError('Subtotal must be positive');
  return subtotal * (1 + taxRate);
}

تعريف الأنواع والأسماء المستعارة (@typedef)

/**
 * @typedef {Object} UserProfile
 * @property {number} id - Unique numeric identifier.
 * @property {string} username - User account handle.
 * @property {string} [email] - Optional contact email address.
 * @property {'admin' | 'editor' | 'member'} role - Access control role.
 */

/**
 * Loads user record from database.
 * @param {number} id
 * @returns {Promise<UserProfile>}
 */
async function getUser(id) {
  // ...
}

وسوم JSDoc الشائعة

المراجع

• الموقع الرسمي لـ JSDoc
• مرجع TypeScript لدعم JSDoc