Apps Script में JSDoc

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: number — गुणा करने के लिए वैल्यू.

आम तौर पर इस्तेमाल होने वाले टैग

ओवरलोड और एक से ज़्यादा टाइप

JavaScript, क्लासिकल फ़ंक्शन ओवरलोडिंग (एक ही नाम वाले कई फ़ंक्शन तय करना) की सुविधा नहीं देता. हालांकि, एक ऐसा फ़ंक्शन लिखा जा सकता है जो अलग-अलग तरह के इनपुट को हैंडल करता हो. JSDoc में, इन "ओवरलोड" बिहेवियर को दस्तावेज़ के तौर पर सेव किया जा सकता है.

यूनियन टाइप

अगर कोई पैरामीटर या रिटर्न वैल्यू, कई टाइप में से कोई एक हो सकती है, तो यूनियन टाइप बनाने के लिए पाइप (|) का इस्तेमाल करें. Apps Script में, यह उन फ़ंक्शन के लिए आम है जो एक वैल्यू या वैल्यू की रेंज (2D अरे के तौर पर दिखाई जाती है) स्वीकार कर सकते हैं.

/**
 * 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=) काम नहीं करता. फ़ॉर्मूला हेल्पर में, सभी पैरामीटर ज़रूरी के तौर पर दिखेंगे.
• डिफ़ॉल्ट वैल्यू: Sheets के यूज़र इंटरफ़ेस (यूआई) में, डिफ़ॉल्ट पैरामीटर वैल्यू (जैसे, [name=Value]) काम नहीं करतीं.
• फ़ॉर्मैटिंग: आपके ब्यौरे में, एचटीएमएल टैग और सामान्य टेक्स्ट लाइन ब्रेक काम नहीं करते. Sheets का यूज़र इंटरफ़ेस (यूआई), ब्यौरे को टेक्स्ट के एक ब्लॉक के तौर पर दिखाता है और ज़्यादातर एचटीएमएल को हटा देता है.

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: ओरिजनल कीमत.

प्रतिशत: छूट का प्रतिशत. जैसे, 10% के लिए 0.1.

ध्यान दें कि पैरामीटर के ब्यौरे, सीधे आपके JSDoc @param टैग से आते हैं.

स्क्रिप्ट-लेवल के एनोटेशन

Apps Script, स्क्रिप्ट-वाइड सेटिंग को कंट्रोल करने के लिए, JSDoc के खास टैग का इस्तेमाल करता है. आम तौर पर, इन्हें स्क्रिप्ट फ़ाइल में सबसे ऊपर रखा जाता है.

अनुमति वाले टैग