JSDoc في "برمجة تطبيقات Google"

المستندات في واجهة مستخدم "جداول بيانات Google" والتعليقات التوضيحية على مستوى البرنامج النصي

تستخدم "برمجة تطبيقات Google" JSDoc لإنشاء مستندات وميزة الإكمال التلقائي للنصوص البرمجية. ‫JSDoc هو معيار لتوثيق رمز JavaScript باستخدام التعليقات.

في برمجة تطبيقات، يخدم JSDoc الأغراض الرئيسية التالية:

1. الإكمال التلقائي في المحرّر: تقديم تلميحات حول المَعلمات وأوصاف الدوال أثناء الكتابة
2. الدوال المخصّصة في "جداول بيانات Google": توثيق الدوال المخصّصة لتظهر في أداة مساعدة الصيغ في "جداول بيانات Google"
3. التعليقات التوضيحية على مستوى النص البرمجي: استخدام علامات خاصة للتحكّم في السلوك على مستوى النص البرمجي، مثل التفويض

وظائف المستند

لتوثيق دالة، ضَع كتلة تعليق JSDoc مباشرةً فوق تعريف الدالة. يبدأ تعليق JSDoc بـ /** وينتهي بـ */.

/**
 * Multiplies an input value by 2.
 *
 * @param {number} input The value to multiply.
 * @return {number} The input multiplied by 2.
 */
function double(input) {
  return input * 2;
}

عند توثيق دالة بهذه الطريقة، يعرض محرر "برمجة تطبيقات Google" تلميحًا خاصًا بالتوثيق عند الإشارة إلى الدالة. على سبيل المثال، عند كتابة double( في المحرّر، يظهر لك ما يلي:

double(input)

تضرب هذه الدالة قيمة الإدخال في 2.

input: رقم — القيمة المطلوب ضربها.

العلامات الشائعة

الحمل الزائد والأنواع المتعددة

على الرغم من أنّ JavaScript لا تتيح تحميل الدوال بشكل كلاسيكي (أي تعريف دوال متعددة بالاسم نفسه)، يمكنك كتابة دالة واحدة تتعامل مع أنواع مختلفة من الإدخالات. يمكنك توثيق هذه السلوكيات "المحمّلة بشكل زائد" في JSDoc.

أنواع الاتحاد

إذا كان بإمكان المَعلمة أو قيمة الإرجاع أن تكون من عدة أنواع، استخدِم علامة الشرطة العمودية (|) لإنشاء نوع اتحاد. ويشيع ذلك في برمجة تطبيقات للدوال التي يمكنها قبول قيمة واحدة أو نطاق من القيم (يتم تمثيله كصفيف ثنائي الأبعاد).

/**
 * Multiplies an input value (or a range of values) by 2.
 *
 * @param {number|number[][]} input The value or 2D array to multiply.
 * @return {number|number[][]} The result.
 */
function double(input) {
  return Array.isArray(input) ?
      input.map(row => row.map(cell => cell * 2)) :
      input * 2;
}

توقيعات متعددة باستخدام @overload

بالنسبة إلى الدوال التي تتضمّن توقيعات معقّدة تعتمد فيها المَعلمات المسموح بها على بعضها البعض، يمكنك استخدام العلامة @overload لتحديد كل توقيع مميّز. يستخدم محرّر "برمجة تطبيقات Google" هذه المعلومات لتقديم تلميحات محدّدة استنادًا إلى إصدار الدالة الذي تستدعيه.

/**
 * @overload
 * @param {string} name The name of the property to get.
 * @return {string} The property value.
 */
/**
 * @overload
 * @param {number} index The index of the item to get.
 * @return {object} The item object.
 */
function get(arg) {
  // Implementation that handles both cases
}

الدوال المخصّصة في "جداول بيانات Google"

عند كتابة دالة مخصّصة في "جداول بيانات Google"، يجب استخدام العلامة @customfunction لكي تظهر في ميزة الإكمال التلقائي ومساعد الصيغ في جدول البيانات.

‫JSDoc هو مصدر النص المساعد الذي يظهر للمستخدمين عند استخدام وظيفتك المخصّصة في "جداول بيانات Google". بدون JSDoc، لن يرى المستخدمون سوى اسم الدالة، ما يصعّب معرفة وظيفتها أو المَعلمات التي تتطلّبها.

العلامات المتوافقة والقيود المفروضة على واجهة المستخدم

على الرغم من أنّ برمجة تطبيقات تحلّل معظم علامات JSDoc العادية، إلا أنّ واجهة مستخدم "جداول بيانات Google" للدوال المخصّصة تتضمّن بعض السلوكيات والقيود المحدّدة:

• ‫@customfunction: مطلوبة لكي تظهر الدالة في قائمة الصيغ في "جداول بيانات Google".
• @param: يتم عرض الاسم والوصف في أداة مساعدة الصيغ في "جداول بيانات Google".
• @return: الوصف المقدَّم في العلامة @return غير معروض في أداة المساعدة في الصيغ في "جداول بيانات Google".
• المَعلمات الاختيارية: لا تتعرّف واجهة مستخدم "جداول بيانات Google" على بنية JSDoc العادية للمَعلمات الاختيارية (مثل [name] أو name=). ستظهر جميع المَعلمات على أنّها مطلوبة في أداة المساعدة في الصيغة.
• القيم التلقائية: لا تتوفّر قيم المَعلمات التلقائية (مثل [name=Value]) في واجهة مستخدم "جداول بيانات Google".
• التنسيق: علامات HTML وفواصل الأسطر في النص العادي غير متاحة في وصفك. تعرض واجهة مستخدم "جداول بيانات Google" الوصف ككتلة نصية واحدة وتزيل معظم رموز HTML.

مثال على "جداول بيانات Google"

/**
 * Calculates a discount.
 *
 * @param {number} price The original price.
 * @param {number} percent The discount percentage (e.g., 0.1 for 10%).
 * @return {number} The price after discount.
 * @customfunction
 */
function calculateDiscount(price, percent) {
  return price * (1 - percent);
}

ما يظهر للمستخدمين في "جداول بيانات Google"

عندما يكتب المستخدم =CALCULATEDISCOUNT( في خلية، تعرض "جداول بيانات Google" مربّع المساعدة التالي:

CALCULATEDISCOUNT

تحسب هذه الدالة قيمة الخصم.

price: السعر الأصلي

percent: النسبة المئوية للخصم (على سبيل المثال، 0.1 لخصم %10).

يُرجى العِلم أنّ أوصاف المَعلمات تأتي مباشرةً من علامات JSDoc @param.

التعليقات التوضيحية على مستوى النص البرمجي

تستخدم "برمجة التطبيقات" علامات JSDoc فريدة للتحكّم في الإعدادات على مستوى البرنامج النصي. ويتم عادةً وضعها في أعلى ملف البرنامج النصي.

علامات التفويض