JSDoc का उपयोग करके जावास्क्रिप्ट कोड का दस्तावेजीकरण कैसे करें

उचित कोड दस्तावेज़ीकरण सॉफ़्टवेयर विकास का एक महत्वपूर्ण लेकिन अक्सर अनदेखा किया जाने वाला पहलू है। एक डेवलपर के रूप में, आप साफ़, कुशल कोड लिखने के आदी होंगे, लेकिन अच्छे दस्तावेज़ लिखने में आपको कम अनुभव हो सकता है।

अच्छा दस्तावेज़ीकरण आपके कोड के साथ काम करने वाले किसी भी व्यक्ति के लिए उपयोगी है, चाहे वह आपकी टीम के अन्य सदस्य हों, या बाद में आप स्वयं हों। यह समझा सकता है कि आपने किसी चीज़ को एक विशेष तरीके से क्यों लागू किया है या किसी विशेष फ़ंक्शन या एपीआई का उपयोग कैसे करें।

जावास्क्रिप्ट डेवलपर्स के लिए, JSDoc आपके कोड का दस्तावेज़ीकरण शुरू करने का एक अच्छा तरीका है।

JSDoc क्या है?

दस्तावेज़ीकरण कोड जटिल और थकाऊ हो सकता है। हालाँकि, अधिक लोग इसके लाभों को पहचान रहे हैं एक "कोड के रूप में दस्तावेज़" दृष्टिकोण, और कई भाषाओं में पुस्तकालय हैं जो प्रक्रिया को स्वचालित करने में मदद करते हैं। सरल, स्पष्ट और संक्षिप्त दस्तावेज़ीकरण के लिए। बिल्कुल वैसे ही

JSDoc आपके जावास्क्रिप्ट स्रोत कोड में विशेष टिप्पणियों की व्याख्या करके, इन टिप्पणियों को संसाधित करके और कस्टम दस्तावेज़ तैयार करके दस्तावेज़ तैयार करता है। इसके बाद यह इस दस्तावेज़ को एक सुलभ HTML प्रारूप में उपलब्ध कराता है।

यह दस्तावेज़ को कोड के भीतर रखता है, इसलिए जब आप अपना कोड अपडेट करते हैं, तो दस्तावेज़ को अपडेट करना आसान होता है।

JSDoc की स्थापना

JSDoc के रचनाकारों ने आपके जावास्क्रिप्ट प्रोजेक्ट में JSDoc को आरंभ करना और स्थापित करना आसान बना दिया है।

JSDoc को स्थानीय रूप से स्थापित करने के लिए, चलाएँ:

npm install --save-dev jsdoc

यह आपके प्रोजेक्ट में लाइब्रेरी को एक देव निर्भरता के रूप में स्थापित करेगा।

JSDoc का उपयोग करने के लिए, आप अपने स्रोत कोड के अंदर विशेष वाक्यविन्यास टिप्पणियों का उपयोग करेंगे। आप अपनी सभी दस्तावेज़ टिप्पणियाँ इसमें लिखेंगे /** और */ मार्कर. इनके अंदर, आप परिभाषित चर, फ़ंक्शन, फ़ंक्शन पैरामीटर और बहुत कुछ का वर्णन कर सकते हैं।

उदाहरण के लिए:

/**
 * Gets User by name.
 * @param {string} name - The name of the User
 * @returns {string} User
 */
functiongetUser(name) {
const User = name;
return User;
}

@परम और @रिटर्न टैग कई विशेष कीवर्ड में से दो हैं जिनका JSDoc आपके कोड को समझाने के लिए समर्थन करता है।

इस कोड के लिए दस्तावेज़ तैयार करने के लिए, चलाएँ एनपीएक्स जेएसडॉक आपकी जावास्क्रिप्ट फ़ाइल के पथ के बाद।

उदाहरण के लिए:

npx jsdoc src/main.js

jsdoc path/to/file.js

यह आदेश एक उत्पन्न करेगा बाहर आपके प्रोजेक्ट रूट में फ़ोल्डर। फ़ोल्डर के अंदर, आपको HTML फ़ाइलें मिलेंगी जो आपके दस्तावेज़ के पृष्ठों का प्रतिनिधित्व करती हैं।

आप इसके द्वारा दस्तावेज़ देख सकते हैं इसे होस्ट करने के लिए एक स्थानीय वेब सर्वर स्थापित करना, या बस ब्राउज़र के अंदर out/index.html फ़ाइल खोलकर। यहां एक उदाहरण दिया गया है कि दस्तावेज़ीकरण पृष्ठ डिफ़ॉल्ट रूप से कैसा दिखेगा:

JSDoc आउटपुट को कॉन्फ़िगर करना

आप JSDoc के डिफ़ॉल्ट व्यवहार को बदलने के लिए एक कॉन्फ़िगरेशन फ़ाइल बना सकते हैं।

ऐसा करने के लिए, एक बनाएं conf.js इस फ़ाइल के अंदर एक जावास्क्रिप्ट मॉड्यूल फ़ाइल करें और निर्यात करें।

उदाहरण के लिए:

module.exports = {
 source: {
 includePattern: ".+\\\\.js(doc|x)?$",
 excludePattern: ["node_modules"],
 },
 recurseDepth: 5,
 sourceType: "module",
 opts: {
 template: "path/to/template",
 destination: "./docs/",
 recurse: true,
 },
};

कॉन्फ़िगरेशन फ़ाइल के अंदर विभिन्न हैं JSDoc कॉन्फ़िगरेशन विकल्प. खाका विकल्प आपको दस्तावेज़ के स्वरूप को अनुकूलित करने के लिए एक टेम्पलेट का उपयोग करने देता है। JSDoc का समुदाय बहुत कुछ प्रदान करता है खाके जिसे आप उपयोग कर सकते हैं. पैकेज आपको अपने स्वयं के वैयक्तिकृत टेम्पलेट बनाने की भी अनुमति देता है।

जनरेट किए गए दस्तावेज़ का स्थान बदलने के लिए, सेट करें गंतव्य किसी निर्देशिका के लिए कॉन्फ़िगरेशन विकल्प। उपरोक्त उदाहरण एक निर्दिष्ट करता है डॉक्स प्रोजेक्ट के रूट में फ़ोल्डर।

कॉन्फ़िगरेशन फ़ाइल के साथ JSDoc चलाने के लिए इस कमांड का उपयोग करें:

jsdoc -c /path/to/conf.js

इस कमांड को चलाना आसान बनाने के लिए, इसे इस रूप में जोड़ें लिपियों आपके अंदर प्रवेश package.json फ़ाइल:

"scripts": {
"dev": "nodemon app.js",
"run-docs": "jsdoc -c /path/to/conf.js"
 },

अब तुम यह कर सकते हो npm स्क्रिप्ट कमांड चलाएँ एक टर्मिनल के अंदर.

JSDoc के साथ तैयार किए गए दस्तावेज़ीकरण का एक उदाहरण

नीचे एक सरल अंकगणित पुस्तकालय है जोड़ना और घटाना तरीके.

यह अच्छी तरह से प्रलेखित जावास्क्रिप्ट कोड का एक उदाहरण है:

/**
 * A library for performing basic arithmetic operations.
 * @module arithmetic
 */
module.exports = {
/**
 * Adds two numbers.
 * @param {number} a - The first number.
 * @param {number} b - The second number.
 * @return {number} The sum of the two numbers.
 * @throws {TypeError} If any of the arguments is not a number.
 * 
 * @example
 * const arithmetic = require('arithmetic');
 * const sum = arithmetic.add(5, 10);
 * console.log(sum); // 15
 */
 add: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
thrownewTypeError('Both arguments must be numbers.');
 }
return a + b;
 },
/**
 * Subtracts the second number from the first number.
 * @param {number} a - The number to subtract from.
 * @param {number} b - The number to subtract.
 * @return {number} The result of the subtraction.
 * @throws {TypeError} If any of the arguments is not a number.
 * 
 * @example
 * const arithmetic = require('arithmetic');
 * const difference = arithmetic.subtract(10, 5);
 * console.log(difference); // 5
 */
 subtract: function(a, b) {
if (typeof a !== 'number' || typeof b !== 'number') {
thrownewTypeError('Both arguments must be numbers.');
 }
return a - b;
 }
//... other methods ...
};

JSDoc टिप्पणियाँ लाइब्रेरी और इसकी विधियों का स्पष्ट और व्यापक विवरण प्रदान करती हैं, जिनमें शामिल हैं:

• पुस्तकालय और उसके उद्देश्य का विवरण।
• प्रत्येक विधि के पैरामीटर, उनके प्रकार और संक्षिप्त विवरण सहित।
• वह मान और प्रकार जो प्रत्येक विधि लौटाती है।
• वे त्रुटियाँ जो प्रत्येक विधि उत्पन्न कर सकती हैं और वे स्थितियाँ जो इसका कारण बनती हैं।
• प्रत्येक विधि का उपयोग कैसे करें इसका एक उदाहरण.

टिप्पणियाँ भी शामिल हैं @मापांक यह इंगित करने के लिए टैग करें कि यह फ़ाइल एक मॉड्यूल है और @उदाहरण प्रत्येक विधि के लिए एक कोड उदाहरण प्रदान करने के लिए टैग।

डेवलपर कोड का सही तरीके से दस्तावेज़ीकरण करना

जैसा कि आप देख सकते हैं, जावास्क्रिप्ट कोड का दस्तावेजीकरण शुरू करने के लिए JSDoc एक बहुत ही उपयोगी उपकरण है। इसके आसान एकीकरण के साथ, आप अपना कोड लिखते समय त्वरित और विस्तृत दस्तावेज़ तैयार कर सकते हैं। आप सीधे अपने कार्यक्षेत्र में दस्तावेज़ों का रखरखाव और अद्यतन भी कर सकते हैं।

हालाँकि, JSDoc का स्वचालन जितना उपयोगी है, आपको अभी भी कुछ दिशानिर्देशों का पालन करना चाहिए ताकि आप गुणवत्तापूर्ण दस्तावेज़ बना सकें।