JSDoc ב-Apps Script

תיעוד בממשק המשתמש של Google Sheets והערות ברמת הסקריפט.

‫Google Apps Script משתמש ב-JSDoc כדי ליצור תיעוד והשלמה אוטומטית לסקריפטים. ‫JSDoc הוא תקן לתיעוד קוד JavaScript באמצעות הערות.

ב-Apps Script, ל-JSDoc יש את המטרות העיקריות הבאות:

1. השלמה אוטומטית בכלי העריכה: הצגת רמזים לפרמטרים ותיאורים של פונקציות בזמן ההקלדה.
2. פונקציות מותאמות אישית ב-Google Sheets: תיעוד של פונקציות מותאמות אישית כדי שהן יופיעו בכלי העזרה לנוסחאות ב-Sheets.
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;
}

כשמתעדים פונקציה בדרך הזו, בכלי לעריכת סקריפטים של Apps Script מוצג הסבר קצר של מאמרי העזרה כשמפנים אליה. לדוגמה, כשמקלידים double( בעורך, רואים:

double(input)

הפונקציה מכפילה ערך קלט ב-2.

‫input: מספר – הערך להכפלה.

תגים נפוצים

תג	תיאור
@param {type} name description	תיעוד של פרמטר בפונקציה. השיטות {type} ו-description משמשות את סביבת הפיתוח למילוי אוטומטי.
@return {type} description	מתעד את ערך ההחזרה של הפונקציה.
@example	דוגמה לאופן השימוש בפונקציה.

עומסים וסוגים מרובים

למרות ש-JavaScript לא תומך בהעמסת פונקציות קלאסית (הגדרה של כמה פונקציות עם אותו שם), אפשר לכתוב פונקציה אחת שמטפלת בסוגים שונים של קלט. אפשר לתעד את ההתנהגויות האלה של 'עומס יתר' ב-JSDoc.

סוגי איחוד

אם פרמטר או ערך החזרה יכולים להיות אחד מכמה סוגים, צריך להשתמש בקו אנכי (|) כדי ליצור סוג איחוד. זה נפוץ ב-Apps Script בפונקציות שיכולות לקבל ערך יחיד או טווח של ערכים (שמיוצג כמערך דו-ממדי).

/**
 * 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 כדי להגדיר כל חתימה נפרדת. הכלי לעריכת סקריפטים של Apps Script משתמש בהן כדי לספק רמזים ספציפיים על סמך הגרסה של הפונקציה שקוראים לה.

/**
 * @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 Sheets

כשכותבים פונקציה בהתאמה אישית ל-Google Sheets, צריך להשתמש בתג @customfunction כדי שהיא תופיע בהשלמה האוטומטית ובכלי העזרה לנוסחאות בגיליון האלקטרוני.

‫JSDoc הוא המקור לטקסט העזרה שהמשתמשים רואים כשהם משתמשים בפונקציה המותאמת אישית שלכם ב-Google Sheets. בלי JSDoc, המשתמשים יראו רק את שם הפונקציה, ולכן יהיה להם קשה לדעת מה הפונקציה עושה או אילו פרמטרים היא דורשת.

תגים נתמכים ומגבלות בממשק המשתמש

‫Apps Script מנתח את רוב תגי JSDoc הרגילים, אבל לממשק המשתמש של Google Sheets לפונקציות מותאמות אישית יש התנהגויות והגבלות ספציפיות:

• ‫@customfunction: נדרש כדי שהפונקציה תופיע ברשימת הנוסחאות של Sheets.
• ‫@param: השם והתיאור מוצגים בכלי העזרה של הנוסחה ב-Sheets.
• ‫@return: התיאור שצוין בתג @return לא מוצג בכלי העזרה לנוסחאות ב-Sheets.
• פרמטרים אופציונליים: ממשק המשתמש של Sheets לא מזהה תחביר JSDoc רגיל לפרמטרים אופציונליים (למשל, [name] או name=). כל הפרמטרים יופיעו כפרמטרים נדרשים בכלי העזרה ליצירת נוסחאות.
• ערכי ברירת מחדל: אין תמיכה בערכי ברירת מחדל של פרמטרים (למשל, [name=Value]) בממשק המשתמש של Sheets.
• עיצוב: אין תמיכה בתגי HTML ובמעברי שורה של טקסט פשוט בתיאור. בממשק המשתמש של Sheets, התיאור מוצג כבלוק טקסט אחד, ורוב ה-HTML מוסר.

דוגמה ל-Google Sheets

/**
 * 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 Sheets

כשמשתמש מקליד =CALCULATEDISCOUNT( בתא, Google Sheets מציג את תיבת העזרה הבאה:

CALCULATEDISCOUNT

מחשבת הנחה.

‫price: המחיר המקורי.

‫percent: אחוז ההנחה (לדוגמה, 0.1 ל-10%).

שימו לב שהתיאורים של הפרמטרים מגיעים ישירות מתגי JSDoc @param.

הערות ברמת הסקריפט

ב-Apps Script נעשה שימוש בתגי JSDoc ייחודיים כדי לשלוט בהגדרות ברמת הסקריפט. הן בדרך כלל ממוקמות בחלק העליון של קובץ סקריפט.

תגי הרשאה

תג	תיאור
@OnlyCurrentDoc	ההגדרה הזו אומרת ל-Apps Script לבקש הרשאה רק למסמך הנוכחי ולא לכל הקבצים מהסוג הזה. לפרטים נוספים, אפשר לעיין ב[מדריך ההרשאות](/apps-script/guides/services/authorization).
@NotOnlyCurrentDoc	משמש בספריות כדי לבטל הערה שעברה בירושה @OnlyCurrentDoc.