TypeScript प्रोजेक्ट के लिए दस्तावेज़ीकरण लिखना: A से Z तक

परिचय: TypeScript प्रोजेक्ट में दस्तावेज़ीकरण की आवश्यकता क्यों है?

गुणवत्तापूर्ण दस्तावेज़ीकरण केवल एक अच्छा बोनस नहीं है, बल्कि किसी भी पेशेवर TypeScript प्रोजेक्ट का एक महत्वपूर्ण तत्व है। यह डेवलपर्स के बीच एक पुल का काम करता है, टीम के नए सदस्यों के ऑनबोर्डिंग को आसान बनाता है, और API का उपयोग करते समय त्रुटियों से बचने में मदद करता है। TypeScript, अपनी शक्तिशाली टाइप सिस्टम के साथ, सटीक और स्व-दस्तावेज़ीकरण उत्पन्न करने के लिए अद्वितीय अवसर प्रदान करता है। इस लेख में, हम पूरी प्रक्रिया को समझेंगे: कोड में टिप्पणियाँ लिखने से लेकर तैयार दस्तावेज़ीकरण प्रकाशित करने तक।

मूल बातें: JSDoc और TypeScript के लिए एनोटेशन

TypeScript JSDoc सिंटैक्स को सपोर्ट करता है, जो आपको सीधे कोड में संरचित टिप्पणियाँ जोड़ने की अनुमति देता है। यह मानव और टूल्स दोनों के लिए समझने योग्य दस्तावेज़ीकरण बनाने का आधार है।

बुनियादी JSDoc टैग

आइए एक सरल फंक्शन के उदाहरण से शुरू करें जो दो संख्याओं को जोड़ता है:

/**\n * दो संख्याओं को जोड़ता है।\n * @param a - पहला जोड़ने वाला नंबर।\n * @param b - दूसरा जोड़ने वाला नंबर।\n * @returns दो संख्याओं का योग।\n */\nfunction add(a: number, b: number): number {\n    return a + b;\n}

मुख्य टैग:

\n
• @param — फंक्शन के आर्गुमेंट का वर्णन करता है। टाइप और उद्देश्य बताने की सिफारिश की जाती है।
\n
• @returns — रिटर्न वैल्यू का वर्णन करता है।
\n
• @throws — बताता है कि फंक्शन कौन से अपवाद फेंक सकता है।
\n
• @example — उपयोग का एक उदाहरण दिखाता है।
\n

जटिल टाइप का दस्तावेज़ीकरण

इंटरफेस और टाइप के लिए, @property का उपयोग करें या ब्लॉक के अंदर फील्ड का वर्णन करें:

interface UserConfig {\n    /** उपयोगकर्ता का नाम */\n    name: string;\n    /** उपयोगकर्ता की आयु (वैकल्पिक) */\n    age?: number;\n    /** सिस्टम में भूमिका */\n    role: 'admin' | 'user';\n}\n\n/**\n * उपयोगकर्ता कॉन्फ़िगरेशन बनाता है।\n * @param config - उपयोगकर्ता सेटिंग्स वाला ऑब्जेक्ट।\n * @returns कॉन्फ़िगरेशन ऑब्जेक्ट।\n */\nfunction createUser(config: UserConfig): UserConfig {\n    return config;\n}

जेनेरिक के लिए @template का उपयोग करें:

/**\n * मान संग्रहीत करने के लिए रैपर।\n * @template T - संग्रहीत मान का प्रकार।\n */\nclass Box<T> {\n    /** संग्रहीत मान */\n    value: T;\n    constructor(value: T) {\n        this.value = value;\n    }\n}

दस्तावेज़ीकरण जनरेशन के लिए टूल्स: TypeDoc

TypeDoc TypeScript में JSDoc एनोटेशन से स्वचालित रूप से दस्तावेज़ीकरण उत्पन्न करने का प्रमुख टूल है। यह आसान नेविगेशन के साथ एक स्टैटिक HTML साइट बनाता है।

इंस्टॉलेशन और सेटअप

TypeDoc को dev-डिपेंडेंसी के रूप में इंस्टॉल करें:

npm install --save-dev typedoc

प्रोजेक्ट की रूट में typedoc.json कॉन्फ़िगरेशन फ़ाइल बनाएं:

{\n  "entryPoints": ["src/index.ts"],\n  "out": "docs",\n  "theme": "default",\n  "excludePrivate": true,\n  "excludeProtected": false,\n  "includeVersion": true,\n  "categorizeByGroup": true\n}

कॉन्फ़िगरेशन पैरामीटर:

\n
• entryPoints — आपके प्रोजेक्ट का एंट्री पॉइंट (आमतौर पर मुख्य एक्सपोर्ट फ़ाइल)।
\n
• out — वह फ़ोल्डर जहाँ दस्तावेज़ीकरण जनरेट होगा।
\n
• excludePrivate — क्लास के प्राइवेट मेंबर्स को छिपाएँ।
\n
• includeVersion — दस्तावेज़ीकरण में प्रोजेक्ट का वर्जन जोड़ें।
\n

जनरेशन चलाना

package.json में एक स्क्रिप्ट जोड़ें:

{\n  "scripts": {\n    "docs:generate": "typedoc"\n  }\n}

कमांड चलाएँ:

npm run docs:generate

इसके बाद, docs फ़ोल्डर में एक स्टैटिक साइट दिखाई देगी। ब्राउज़र में docs/index.html खोलें।

दस्तावेज़ीकरण लिखने के सर्वोत्तम अभ्यास

दस्तावेज़ीकरण को उपयोगी बनाने के लिए, कुछ नियमों का पालन करें।

1. टिप्पणियाँ स्पष्ट और संक्षिप्त लिखें