🍦 👩🏾‍✈️ 🆚 लेखन दस्तावेज ⏬ 👨‍🌾 👨‍🔧

यदि आप ओपन सोर्स डॉक्यूमेंटेशन लिखते हैं, तो यह केवल परियोजनाओं के लिए एक विनम्र जोड़ नहीं है, यह आपकी परियोजना को एक निश्चित सीमा तक ले जाने में मदद करता है। एक अच्छी तरह से लिखा README मदद करता है, लेकिन पूर्ण एपीआई प्रलेखन परियोजना को और अधिक पेशेवर बनाता है। यहां तक कि अगर आपकी परियोजना बंद स्रोत है, तो दस्तावेज़ नए सहयोगियों को अधिक तेज़ी से अनुकूलित करने में मदद करेगा या आपको यह याद रखने में मदद करेगा कि दीर्घकालिक परियोजनाओं में सब कुछ कैसे काम करता है।

आइए देखें कि लोकप्रिय जावास्क्रिप्ट फ्रेमवर्क में प्रलेखन कैसे काम करता है।

jQuery

JQuery प्रलेखन docs.jquery.com पर स्थित है और एक विकि है जो सभी एपीआई प्रलेखन का वर्णन करता है। एपीआई के किसी भी बड़े क्षेत्र को नेविगेशन में शामिल किया गया है, प्रत्येक पृष्ठ में इस क्षेत्र के तरीकों की एक सूची है। पृष्ठ में कोड उदाहरण और डिस्कस पर टिप्पणियां शामिल हैं।

स्रोत कोड टिप्पणियाँ मुख्य रूप से बग या कोड के एक असामान्य टुकड़े से संबंधित हैं जिन्हें स्पष्टीकरण की आवश्यकता है।

अगला: प्रोटोटाइप, JSDoc, और कुछ विशिष्ट जावास्क्रिप्ट प्रलेखन दृष्टिकोण

प्रोटोटाइप

प्रोटोटाइप प्रलेखन api.prototypjs.org पर उपलब्ध है। यह pdoc के उपयोग से उत्पन्न होता है । PDoc है:

... इनलाइन टिप्पणी पार्सर और एक जावास्क्रिप्ट प्रलेखन जनरेटर रूबी में लिखा गया है। यह प्रोटोटाइप प्रलेखन और प्रोटोटाइप में लिखे गए पुस्तकालयों के लिए डिज़ाइन किया गया है।

प्रोटोटाइप टिप्पणी मार्कडाउन कोड है जिसे दस्तावेज़ में पीडीओ द्वारा परिवर्तित किया जा सकता है।

एक उदाहरण के लिए, github.com/sstephenson/prototype/blob/master/src/prototyp/ajax.js पर एक नज़र डालें

/** 
      

        
        
        
      

     * == Ajax == 
      

        
        
        
      

     * 
      

        
        
        
      

     * Prototype's APIs around the `XmlHttpRequest` object. 
      

        
        
        
      

     * 
      

        
        
        
      

     * The Prototype framework enables you to deal with Ajax calls in a manner that 
      

        
        
        
      

     * is both easy and compatible with all modern browsers. 
      

        
        
        
      

     * 
      

        
        
        
      

     * Actual requests are made by creating instances of [[Ajax.Request]]. 
      

        
        
        
      

     */

JQuery के विपरीत, प्रोटोटाइप प्रलेखन स्रोत कोड के अंदर है।

JSDoc

JSDoc इनलाइन प्रलेखन लिखने का एक तरीका भी है। टिप्पणियां मेटाडेटा के लिए @ विशेष चरित्र के साथ शुरू हो सकती हैं:

/** 
      

        
        
        
      

     * Example constructor. 
      

        
        
        
      

     * 
      

        
        
        
      

     * @constructor 
      

        
        
        
      

     * @this {Example} 
      

        
        
        
      

     */

Jsdoc-टूलकिट का उपयोग करके पूर्ण HTML प्रलेखन उत्पन्न किया जा सकता है। इनलाइन JSDoc के साथ जावास्क्रिप्ट प्रोजेक्ट HTML डॉक्यूमेंट जनरेट करने के लिए dox का उपयोग कर सकते हैं।

Docco

Docco MIT लाइसेंस के तहत जेरेमी एशकेनस द्वारा लिखित एक प्रलेखन जनरेटर है। डोको इनलाइन प्रलेखन स्रोत कोड से HTML उत्पन्न करता है। डोको प्रलेखन एक html पृष्ठ है जिसमें स्रोत कोड और प्रलेखन दोनों प्रस्तुत किए जाते हैं। Jashkenas.github.com/docco पर एक नज़र डालें Docco को स्थापित करना आसान है: npm install docco

यह एक सरल पुस्तकालय है जिसका उपयोग करना आसान है यदि आप पहले से ही नोड का उपयोग कर रहे हैं। यदि आप अपने प्रोजेक्ट पर डोकलाम आज़माना चाहते हैं, तो इसे स्थापित करें और अपने प्रोजेक्ट रन की मूल निर्देशिका से: docco *.js

यह असामान्य है कि Docco टिप्पणियों के बगल में स्रोत कोड रखता है। बदले में JSDoc प्रोटोटाइप या jQuery प्रलेखन के समान कुछ उत्पन्न करेगा। मैंने देखा कि नोड के लिए कई सरल पुस्तकालय डोको का उपयोग करते हैं।

Ronn

रॉन Tomayko और ronnjs द्वारा लिखित Ronn , फ़ाइलों के एक सेट से प्रलेखन उत्पन्न करने के लिए इस्तेमाल किया जा सकता है। ronnjs हमें केवल मार्कडाउन फ़ाइलों तक सीमित करता है। परिणाम HTML या मानव-प्रलेखन के रूप में प्रस्तुत किया जा सकता है। रॉन नाम रफ़ से आया है।

गितुब विकी

GitHub प्रोजेक्ट में विकी है, स्रोत wiki मार्कअप Git में संग्रहीत है। विकी पृष्ठ आसानी से पाठ प्रारूप में लिखे जा सकते हैं। यहाँ एक GitHub ब्लॉग पोस्ट है जो कुछ विशेषताओं का वर्णन करता है: Git-समर्थित Wikis । यह उन परियोजनाओं के लिए एक महान उपकरण है, जिन्हें एपीआई से बाहर प्रलेखन की आवश्यकता होती है, जैसे एफएक्यू, स्थापना प्रक्रिया और नमूना कोड।

GitHub में GitHub पेज भी हैं, जिसका उपयोग आपके you.github.com पेज पर स्थिर फ़ाइलों को होस्ट करने के लिए किया जा सकता है। GitHub पेज का उपयोग डोको या डॉक्स द्वारा उत्पन्न प्रलेखन को संग्रहीत करने के लिए किया जा सकता है।

अनुवादक से

अनुवाद के दौरान, पाठ के महत्वहीन ब्लॉक, जो पोस्ट के विषय से विचलन हैं, हटा दिए गए थे।

डोको वास्तव में उतना अच्छा नहीं है जितना कि यह पहली नज़र में लगता है, इसके लिए एक विशेष प्रकार की टिप्पणियों की आवश्यकता होती है (मार्कडाउन में लिखित एकल-पंक्ति टिप्पणियाँ)

वह ब्लॉक कमेंट्स को नहीं समझता है। पाइथन में लिखे गए पायको ~~रुसो-पर्यटक~~ का एक एनालॉग है, यह बिल्कुल उसी दस्तावेज को उत्पन्न करता है और ब्लॉक टिप्पणियों को समझता है, लेकिन फिर से जेएसडीओसी ब्लॉकों को नहीं समझता है और उन्हें विकृत करता है (यह मेटा टैग के बारे में नहीं है)।

अब मैं थोड़ा संशोधित डिफ़ॉल्ट JSDoc टेम्प्लेट का उपयोग करता हूं (JSDoc de facto प्रलेखन मानक है)। लेख पढ़ने के बाद, मैंने dox पर स्विच करने के बारे में सोचा:

... मुझे कुछ चाहिए था जो मेरे जावास्क्रिप्ट को मार्कडाउन और जेएसडीओसी टैग का उपयोग करके पार्स कर सकता है ...

यह बहुत अच्छा नहीं है ?!

आप किस कोड प्रलेखन टूल का उपयोग करते हैं? आप क्या अच्छे उपकरण जानते हैं?

लेखन दस्तावेज