अपने दस्तावेज़ में मेटाडेटा जोड़ना
प्रत्येक डेवलपर के लिए अच्छा दस्तावेज़ीकरण प्रदान करना एक आवश्यक कार्य है। यह न केवल आपके साथियों को आपके तर्क और शायद विचार प्रक्रिया को जल्दी से समझने में मदद करता है, बल्कि यदि आप कुछ महीनों के बाद उस पर वापस आते हैं तो यह आपको कोड में तेजी से आने में भी मदद करता है।
इसलिए मैंने JSDoc-टिप्पणियों के साथ उपयोग करने के लिए विशेष टैग की एक (अपूर्ण) सूची बनाने का विचार किया। वे वे हैं जिनका मैं व्यक्तिगत रूप से सबसे अधिक बार उपयोग करता हूं और जो एक वास्तविक लाभ प्रदान करने के लिए सिद्ध हुए हैं।
एक बुनियादी स्टार्टर
निम्न कोड उदाहरण एक सरल, मूल उदाहरण दिखाता है जिसका उपयोग प्रत्येक दस्तावेज़ के लिए किया जाना चाहिए। यह उद्देश्य, मापदंडों के साथ-साथ रिटर्न प्रकार की व्याख्या करता है।
/**
* Get a sum all terms provided.
*
* @param {...number} terms Array of terms to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
दस्तावेज़ीकरण में उदाहरण कोड
कुछ उपयोग के मामलों को स्पष्ट करने के लिए आप "@example" -tag के साथ एक वास्तविक इनलाइन कोड उदाहरण प्रदान कर सकते हैं। इस टैग का उपयोग वास्तविक दुनिया के परिदृश्य में संभावित किनारे के मामलों को शीघ्रता से दिखाने के लिए भी किया जा सकता है।
/**
* Get a sum all terms provided.
*
* @example
* ```ts
* import { sum } from "./source";
* const result = sum(40, 2);
* ```
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
किस मॉड्यूल के सदस्य
दस्तावेज़ कोड को कौन सा मॉड्यूल या पैरेंट वेरिएबल होस्ट करता है, यह परिभाषित करने के लिए "@memberOf" -tag का उपयोग करें।
/**
* @memberOf module:source
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
लिंक एनोटेशन
आप मुख्य दस्तावेज़ के कुछ URL को इनलाइन चिपकाने के बजाय, एक सही स्वरूपित URL-दस्तावेज़ीकरण प्रदान करने के लिए "@link" -tag के साथ "@see" -tag का उपयोग कर सकते हैं।
/**
* @see (@link module:source.sum}
* @see (@link https://www.some-source.com}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
सामान्य प्रकार के दस्तावेज़ीकरण
यदि आपका कोड सामान्य प्रकार का उपयोग करता है, तो आप सामान्य प्रकार के नाम को परिभाषित करने के लिए "@template" -टैग का उपयोग कर सकते हैं। यह नाम तब सामान्य "@param" -टैग में टाइप संदर्भ के रूप में उपयोग किया जाता है।
/**
* @template T
* @param {...T} Array of numbers to sum up.
* @returns {number} Sum of terms.
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
कोड के एक टुकड़े के लेखक को परिभाषित करना
कुछ मामलों में, लेखक को भी एनोटेट करना महत्वपूर्ण है। यह केवल "@author" -tag के साथ पूरा किया जा सकता है। आप न केवल अपना नाम, बल्कि संपर्क संदर्भ के रूप में एक ईमेल भी प्रदान कर सकते हैं।
/**
* @author Tom Schönmann <[email protected]>
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
पदावनत कोड
"@deprecated" -tag के बारे में बताने के लिए बहुत कुछ नहीं है, क्योंकि यह वही करता है जिसकी आप अपेक्षा करते हैं। यह टैग आमतौर पर एपीआई में उपयोग किया जाता है और नए कोड को भी संदर्भित कर सकता है।
/**
* @deprecated Use 'add(...)' instead.
* @see {@link module:source/add}
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
संस्करण
दिए गए कोड के लिए एक संस्करण का दस्तावेजीकरण करने के लिए "@version" -tag का उपयोग करें। ध्यान दें कि यह टैग एप्लिकेशन संस्करण का संदर्भ नहीं देता है, लेकिन वास्तव में इसका अपना संस्करण है। इस संस्करण की वृद्धि का अर्थ है कि यह विशिष्ट कोड बदल गया है।
/**
* @version 1.0.0
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
जब से कोड उपयोग के लिए उपलब्ध है
आप "@ से" -टैग का उपयोग दस्तावेज़ के लिए कर सकते हैं कि किस संस्करण संख्या से निम्नलिखित कोड को सार्वजनिक एपीआई में जोड़ा गया है। यहां ध्यान देने योग्य बात यह है कि संस्करण अब एप्लिकेशन-स्कोप का संदर्भ देता है। यह पहले के "@version" -टैग के साथ विरोधाभासी है, जो विशिष्ट कोड के दायरे में है जो इसे दस्तावेज़ों को ब्लॉक करता है।
/**
* @since 2.0.1
*/
export function sum(...terms: number[]){
return terms.reduce((acc,cv) => acc + cv, 0);
}
