जब आप प्रोग्रामिंग के बारे में सोचते हैं, तो भाषाओं, एल्गोरिदम और डिबगिंग जैसे विषयों पर ध्यान देना स्वाभाविक है। लेकिन तकनीकी दस्तावेज सही होने के लिए उतने ही महत्वपूर्ण हो सकते हैं।

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

जावा के लिए पाइडोक और जावा के लिए जावाडोक जैसे पैकेज प्रक्रिया के हिस्से को स्वचालित करके मदद करते हैं। गोडोक टूल गो के लिए ठीक वैसा ही करता है।

गोडोक क्या है?

गोडोक एक गो पैकेज है जो आपको "गो वे" में गो दस्तावेज बनाने, प्रबंधित करने और उपयोग करने देता है। गो वे सिद्धांतों का एक समूह है, जिसे गो प्रोग्रामर के रूप में, आपको कोड गुणवत्ता में सुधार करने के लिए पालन करना चाहिए।

गोडोक का उपयोग करके, आप अन्य डेवलपर्स के दस्तावेज़ और कोड को आसानी से पढ़ सकते हैं। आप अपने स्वयं के दस्तावेज़ों के निर्माण को स्वचालित भी कर सकते हैं और इसे गोडोक का उपयोग करके प्रकाशित कर सकते हैं।

instagram viewer

गोडोक के समान है Javadoc, Java के लिए कोड डॉक्यूमेंटर. वे दोनों दस्तावेज़ बनाने के लिए मॉड्यूल में टिप्पणियों और कोड का उपयोग करते हैं। और दोनों उपकरण HTML में उस दस्तावेज़ीकरण की संरचना करते हैं ताकि आप इसे ब्राउज़र में देख सकें।

गोडोक के साथ शुरुआत करना

गोडोक का उपयोग करना आसान है। शुरू करने के लिए, इस आदेश का उपयोग करके गोलांग वेबसाइट से गोडोक पैकेज स्थापित करें:

जाओ golang.org/x/tools/cmd/godoc. प्राप्त करें

इस आदेश को चलाने से आपके निर्दिष्ट कार्यक्षेत्र में Godoc स्थापित हो जाएगा। एक बार जब यह पूरा हो जाता है, तो आपको चलाने में सक्षम होना चाहिए गोडोक एक टर्मिनल में कमांड। यदि आपके इंस्टॉलेशन में कोई त्रुटि है, तो गो को हाल के संस्करण में अपडेट करने का प्रयास करें।

गोडोक अपने द्वारा जेनरेट किए गए दस्तावेज़ीकरण में शामिल करने के लिए सिंगल और मल्टीपल लाइन टिप्पणियों की तलाश करता है।

कोड को गो वे में प्रारूपित करना सुनिश्चित करें, जैसा कि में बताया गया है द इफेक्टिव गो पब्लिकेशन पाएँ बेहतर परिणामों के लिए गो टीम.

यहाँ C++ - स्टाइल सिंगल-लाइन टिप्पणियों का उपयोग करते हुए एक उदाहरण दिया गया है:

// उपयोगकर्ता एक संरचना मॉडल है जिसमें शामिल है
प्रकार उपयोगकर्ता struct {
}

आप सी-स्टाइल ब्लॉक टिप्पणियों का भी उपयोग कर सकते हैं:

/* 
उपयोगकर्ता एक कस्टम डेटा संरचना है
आप यहां कोई भी टेक्स्ट शामिल कर सकते हैं और जब आप इसे चलाते हैं तो गोडोक सर्वर इसे प्रारूपित कर देगा।
*/
प्रकार उपयोगकर्ता struct {
}

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

गोडोक सर्वर चलाना

एक बार जब आप अपने कोड पर टिप्पणी कर लेते हैं, तो आप इसे चला सकते हैं गोडोक अपने प्रोजेक्ट के कोड डायरेक्टरी से अपने टर्मिनल में कमांड करें।

परंपरागत रूप से, गो डेवलपर्स पोर्ट का उपयोग करते हैं 6060 प्रलेखन की मेजबानी करने के लिए। उस पोर्ट पर एक गोडोक सर्वर चलाने के लिए यह कमांड है:

गोडोक -http=:6060

ऊपर दिया गया कमांड आपके कोड प्रलेखन को होस्ट करता है लोकलहोस्ट, या 127.0.0.1. बंदरगाह के लिए 6060 नहीं है; गोडोक किसी भी खाली बंदरगाह पर चलेगा। हालांकि, गो प्रलेखन सम्मेलनों का पालन करना हमेशा सर्वोत्तम होता है।

एक बार जब आप कमांड चला लेते हैं, तो आप एक ब्राउज़र में जाकर अपने दस्तावेज़ देख सकते हैं लोकलहोस्ट: 6060. आपके दस्तावेज़ को तैयार करने में Godoc को लगने वाला समय उसके आकार और जटिलता पर निर्भर करेगा।

नीचे दिया गया कोड गो वे का पालन करता है, इस मामले में सिंगल-लाइन टिप्पणियों का उपयोग करते हुए।

// पैकेज का नाम
पैकेट उपयोगकर्ता
// fmt स्वरूपण के लिए जिम्मेदार है
आयात (
 "एफएमटी"
)


// उपयोगकर्ता मानव डेटा की एक संरचना है
प्रकार उपयोगकर्ता struct {
 आयु पूर्णांक
 नाम डोरी
}


समारोहमुख्य() {
// मानव उपयोगकर्ता संरचना का एक आरंभीकरण है
 मानव: = उपयोगकर्ता {
 आयु: 0,
 नाम: "व्यक्ति",
 }


एफएमटी प्रिंट्लन (मानव। बात करना())
}
// टॉक यूजर स्ट्रक्चर की एक विधि है
समारोह(रिसीवर उपयोगकर्ता)बात करना()डोरी {
वापसी "हर उपयोगकर्ता को कुछ न कुछ कहना होता है!"
}

यदि आप ऊपर दिए गए कोड मॉड्यूल पर Godoc चलाते हैं, तो आपको आउटपुट कुछ इस तरह दिखना चाहिए:

ध्यान दें कि यह एक परिचित प्रारूप में है, जो आपको गो आधिकारिक दस्तावेज़ीकरण वेबसाइट पर मिलेगा।

गोडोक पैकेज घोषणा से पहले की टिप्पणी का उपयोग करता है: अवलोकन. सुनिश्चित करें कि यह टिप्पणी बताती है कि आपका प्रोग्राम क्या करता है।

अनुक्रमणिका प्रकार की घोषणाओं और विधियों के लिंक होते हैं ताकि आप उन्हें जल्दी से नेविगेट कर सकें।

गोडोक उस स्रोत कोड को देखने के लिए कार्यक्षमता भी प्रदान करता है जो पैकेज को बनाता है पैकेज फ़ाइलें खंड।

Godoc का उपयोग करके अपने दस्तावेज़ में सुधार करना

आप अपने गोडोक दस्तावेज़ में केवल सादा पाठ से अधिक शामिल कर सकते हैं। आप उन URL को जोड़ सकते हैं जिनके लिए Godoc लिंक जेनरेट करेगा और आपकी टिप्पणियों को पैराग्राफ में संरचित करेगा।

यदि आप किसी संसाधन से लिंक करना चाहते हैं, तो अपनी टिप्पणी में URL लिखें, और Godoc इसे पहचान लेगा और एक लिंक जोड़ देगा। पैराग्राफ के लिए, एक खाली टिप्पणी लाइन छोड़ दें।

// पैकेज मुख्य
पैकेट मुख्य
// दस्तावेज़ एक नियमित दस्तावेज़ का प्रतिनिधित्व करता है।
//
// से लिंक करें https://google.com
प्रकार दस्तावेज़ struct {
 पृष्ठों पूर्णांक
 संदर्भ डोरी
 पर हस्ताक्षर किए बूल
}


// लिखें भंडारण के लिए एक नया दस्तावेज़ लिखता है
//
// आप विकिपीडिया.com से लिखने के बारे में जान सकते हैं
समारोहलिखना() {
}

ध्यान दें कि Godoc के लिए आवश्यक है कि आप उन्हें लिंक करने के लिए URL को पूरा लिखें। इस उदाहरण में, Google URL में शामिल हैं: https:// उपसर्ग, इसलिए गोडोक इसमें एक लिंक जोड़ता है। चूंकि विकिपीडिया डोमेन अपने आप में एक पूर्ण URL नहीं है, इसलिए गोडोक इसे अकेला छोड़ देगा।

अपने गो कोड का दस्तावेजीकरण करते समय लागू करने के लिए यहां कुछ सर्वोत्तम सिद्धांत दिए गए हैं:

  • अपने दस्तावेज़ीकरण को सरल और संक्षिप्त रखें।
  • कार्यों, प्रकारों और चर घोषणाओं के वाक्यों को उनके नाम से शुरू करें।
  • कोड के रूप में इसे पूर्व-प्रारूपित करने के लिए एक इंडेंट के साथ एक लाइन शुरू करें।
  • "बग (नाम)" से शुरू होने वाली टिप्पणियां जैसे "बग (जो): यह काम नहीं करता" विशेष हैं। गोडोक उन्हें बग के रूप में पहचानेगा और दस्तावेज़ीकरण के अपने अनुभाग में उनकी रिपोर्ट करेगा।

गोडोक आपके दस्तावेज़ीकरण की समस्या को कम कर सकता है

गोडोक का उपयोग करके, आप अधिक उत्पादक हो सकते हैं और अपने कार्यक्रमों को हाथ से दस्तावेज करने के प्रयास के बारे में चिंता कम कर सकते हैं।

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

गोडोक का उपयोग करने के बारे में अधिक जानने के लिए गोडोक पैकेज दस्तावेज देखें।