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: संख्या — वह वैल्यू जिससे गुणा करना है.

सामान्य टैग

टैग	ब्यौरा
@param {type} name description	यह फ़ंक्शन के पैरामीटर के बारे में जानकारी देता है. {type} और description का इस्तेमाल, डेवलपमेंट एनवायरमेंट में ऑटोकंप्लीट के लिए किया जाता है.
@return {type} description	फ़ंक्शन की रिटर्न वैल्यू के बारे में बताता है.
@example	इस फ़ंक्शन के इस्तेमाल का तरीका बताता है.

ओवरलोड और कई तरह के

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: मूल कीमत.

percent: छूट का प्रतिशत (उदाहरण के लिए, 10% के लिए 0.1).

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

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

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

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

टैग	ब्यौरा
@OnlyCurrentDoc	Apps Script को सिर्फ़ मौजूदा दस्तावेज़ के लिए अनुमति का अनुरोध करने के लिए कहता है, न कि उस तरह की सभी फ़ाइलों के लिए. ज़्यादा जानकारी के लिए, [Authorization guide](/apps-script/guides/services/authorization) देखें.
@NotOnlyCurrentDoc	इस एनोटेशन का इस्तेमाल लाइब्रेरी में, इनहेरिट किए गए @OnlyCurrentDoc एनोटेशन को बदलने के लिए किया जाता है.