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

C# प्रोजेक्ट के गुणवत्तापूर्ण दस्तावेज़ीकरण की आवश्यकता क्यों है?

दस्तावेज़ीकरण डेवलपर और आपके कोड के उपयोगकर्ता के बीच एक पुल है। C# (.NET) की दुनिया में, यह पुल XML-कमेंट्री और विशेष उपकरणों (DocFX, Sandcastle) की मदद से बनाया जाता है। अच्छा दस्तावेज़ीकरण:

\n
• प्रोजेक्ट में नए डेवलपर्स को शामिल करने की प्रक्रिया को तेज़ करता है
\n
• चैट और टिकटों में प्रश्नों की संख्या कम करता है
\n
• कोड की गुणवत्ता में सुधार करता है (जब आप खराब मेथड के लिए दस्तावेज़ लिखते हैं, तो आप अनजाने में उन्हें रीफैक्टर करते हैं)
\n
• स्वचालित रूप से API संदर्भ (Visual Studio में IntelliSense) उत्पन्न करता है
\n

इस लेख में, हम पूर्ण चक्र पर चर्चा करेंगे: प्रोजेक्ट सेटअप से लेकर स्टैटिक साइट पर दस्तावेज़ीकरण प्रकाशित करने तक। सभी उदाहरण C# (.NET 8) में हैं।

1. XML-कमेंट्री: C# में दस्तावेज़ीकरण का आधार

1.1. XML फ़ाइल जनरेशन कैसे सक्षम करें

Visual Studio (या Rider) स्वचालित रूप से कमेंट्री के साथ XML फ़ाइल बनाता है, यदि आप .csproj में संबंधित विकल्प सक्षम करते हैं:

<PropertyGroup>\n    <GenerateDocumentationFile>true</GenerateDocumentationFile>\n    <DocumentationFile>bin\\$(Configuration)\\$(TargetFramework)\\$(AssemblyName).xml</DocumentationFile>\n</PropertyGroup>

बिल्ड के बाद, bin/Debug/net8.0/ फ़ोल्डर में आपकी कमेंट्री के साथ एक XML फ़ाइल दिखाई देगी। यह फ़ाइल DocFX और Sandcastle के लिए कच्चा माल है।

1.2. मुख्य XML टैग

C# प्रोजेक्ट दस्तावेज़ीकरण लिखने के लिए निम्नलिखित टैग का उपयोग करें:

\n
• <summary> — क्लास, मेथड, प्रॉपर्टी का संक्षिप्त विवरण।
\n
• <param name="..."> — मेथड पैरामीटर का विवरण।
\n
• <returns> — वापसी मान का विवरण।
\n
• <exception cref="..."> — मेथड कौन से अपवाद फेंक सकता है।
\n
• <example> — उपयोग का उदाहरण।
\n
• <see cref="..."> — किसी अन्य प्रकार या मेथड का लिंक।
\n
• <code> — विवरण के अंदर फ़ॉर्मेटेड कोड।
\n

1.3. पूर्ण कमेंट्री का उदाहरण

/// <summary>\n/// शून्य की जाँच के साथ दो संख्याओं का सुरक्षित विभाजन करता है।\n/// </summary>\n/// <param name="dividend">भाज्य (अंश)।</param>\n/// <param name="divisor">भाजक (हर)। 0 के बराबर नहीं हो सकता।</param>\n/// <returns>दशमलव भिन्न के रूप में विभाजन का परिणाम।</returns>\n/// <exception cref="DivideByZeroException">यदि divisor 0 है तो फेंका जाता है।</exception>\n/// <example>\n/// <code>\n/// double result = SafeDivider.Divide(10, 3);\n/// Console.WriteLine(result); // 3.333...\n/// </code>\n/// </example>\npublic static double Divide(double dividend, double divisor)\n{\n    if (divisor == 0)\n        throw new DivideByZeroException("शून्य से विभाजन निषिद्ध है।");\n    return dividend / divisor;\n}

सुझाव: यदि प्रोजेक्ट आंतरिक है तो हिंदी में कमेंट्री लिखें, या खुले API के लिए अंग्रेजी में। मुख्य बात एक समान शैली बनाए रखना है।

2. दस्तावेज़ीकरण जनरेशन उपकरण: DocFX बनाम Sandcastle

2.1. DocFX (अनुशंसित)

DocFX Microsoft का एक आधुनिक उपकरण है जो XML-कमेंट्री और अतिरिक्त Markdown फ़ाइलों से एक स्टैटिक साइट उत्पन्न करता है। यह C#, VB.NET और यहाँ तक कि JavaScript का समर्थन करता है।

स्थापना:

dotnet tool install -g docfx

त्वरित आरंभ:

docfx init -o my-docs\ncd my-docs\ndocfx build\ndocfx serve _site

DocFX स्वचालित रूप से:

\n
• आपकी .csproj और .sln फ़ाइलों को स्कैन करता है
\n
• XML-कमेंट्री निकालता है
\n
• प्रत्येक क्लास, मेथड, प्रॉपर्टी के लिए पेज बनाता है
\n
• नेविगेशन, खोज और सुंदर थीम (डिफ़ॉल्ट रूप से Bootstrap) जोड़ता है
\n