जावाडोक के साथ अपने जावा कोड को स्वचालित रूप से दस्तावेज करें

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

जावा आसानी से समस्या का एक अंतर्निहित समाधान प्रदान करता है: जावाडोक।

जावाडोक आपके कोड को स्वचालित रूप से दस्तावेज करने में आपकी सहायता कर सकता है

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

निश्चित रूप से, एक अन्य प्रोग्रामर आपके कोड को देख सकता है और विशिष्ट वर्गों, विधियों और कार्यों के बारे में पढ़ सकता है जो उसके सामने हैं। हालाँकि, सभी कोड का एक अच्छा अवलोकन प्राप्त करना या ऐसे फ़ंक्शन ढूंढना बेहद मुश्किल है जो तब उपयोगी हो सकते हैं जब आप नहीं जानते कि वे मौजूद हैं। जावाडोक का लक्ष्य उस समस्या को हल करना है।

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

जावाडोक वास्तव में क्या है और यह कैसे काम करता है?

जावाडोक एक स्टैंडअलोन प्रोग्राम है जो ओरेकल के जावा डेवलपमेंट किट (जेडीके) रिलीज के साथ बंडल में आता है। वास्तव में, आप इसे अलग से डाउनलोड नहीं कर सकते। जब आप डाउनलोड करते हैं और Oracle के JDK संस्करणों में से एक को स्थापित करें, यह जावाडोक भी स्थापित करेगा।

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

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

Javadoc आपके कोड में विशेष रूप से स्वरूपित टिप्पणियों को पार्स करके और उन्हें HTML आउटपुट में परिवर्तित करके काम करता है। केवल एक ही परिवर्तन जो आपको वास्तव में करने की आवश्यकता है, वह है अपनी टिप्पणियों में कुछ स्ट्रिंग्स को शामिल करना। ये जावाडोक को यह बताते हैं कि आप अंतिम दस्तावेज में क्या शामिल करना चाहते हैं।

Javadoc टिप्पणियों को तुरंत एक वर्ग, क्षेत्र, निर्माता, या विधि घोषणा से पहले होना चाहिए। टिप्पणी स्वयं होनी चाहिए:

• तीन वर्णों से शुरू करें /**.
• प्रत्येक नई पंक्ति की शुरुआत में एक तारांकन चिह्न शामिल करें।
• दो पात्रों के साथ बंद करें */.

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

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

/**
* एक छवि वस्तु देता है जिसे तब स्क्रीन पर चित्रित किया जा सकता है।
* url तर्क को एक निरपेक्ष निर्दिष्ट करना चाहिए {@संपर्क यूआरएल}. नाम
* तर्क एक विनिर्देशक है जो url तर्क के सापेक्ष है।
* 

* यह विधि हमेशा तुरंत लौटती है, चाहे
* छवि मौजूद है। कब यह एप्लेट छवि को खींचने का प्रयास करता है
* स्क्रीन, डेटा लोड किया जाएगा। ग्राफिक्स आदिम
* जो छवि खींचता है वह स्क्रीन पर धीरे-धीरे पेंट करेगा।
*
* @परम यूआरएल छवि का आधार स्थान देने वाला एक पूर्ण यूआरएल
* @परम यूआरएल तर्क के सापेक्ष छवि के स्थान को नाम दें
* @वापसी निर्दिष्ट URL पर छवि
* @देखना छवि
*/
जनता छवि छवि प्राप्त करें(यूआरएल यूआरएल, स्ट्रिंग नाम){
प्रयत्न {
वापसी छवि प्राप्त करें (नया यूआरएल (यूआरएल, नाम));
 } पकड़ (विकृत URL अपवाद ई) {
वापसीशून्य;
 }
}

जब जावाडोक उपरोक्त कोड को संसाधित करता है, तो यह निम्न के जैसा एक वेब पेज उत्पन्न करता है:

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

टिप्पणी के अंत में उपयोग किए गए @tags उत्पन्न करते हैं मापदंडों, रिटर्न, तथा यह सभी देखें अनुभाग जो आप देखते हैं।

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

@वापसी टैग उस मान को दस्तावेज़ करता है जो फ़ंक्शन देता है, यदि बिल्कुल भी। यह परिस्थितियों के आधार पर एक साधारण एक शब्द का विवरण या कई वाक्य हो सकता है।

@देखना टैग आपको अन्य कार्यों को टैग करने की अनुमति देता है जो संबंधित या प्रासंगिक हैं। इस मामले में, @see टैग एक अन्य फ़ंक्शन को संदर्भित करता है जिसे केवल छवि कहा जाता है। ध्यान दें कि इस टैग के साथ किए गए संदर्भ क्लिक करने योग्य लिंक हैं, जिससे पाठक अंतिम HTML में संदर्भित आइटम पर जा सकते हैं।

और भी टैग उपलब्ध हैं जैसे @version, @author, @exception, और अन्य। जब ठीक से उपयोग किया जाता है, तो टैग एक-दूसरे से वस्तुओं को जोड़ने में मदद करते हैं और दस्तावेज़ीकरण के माध्यम से आसानी से नेविगेट करना संभव बनाते हैं।

अपने स्रोत कोड पर जावाडोक चलाना

आप कमांड लाइन पर जावाडोक का आह्वान करते हैं। आप इसे एकल फाइलों, संपूर्ण निर्देशिकाओं, जावा पैकेजों या अलग-अलग फाइलों की सूची में चला सकते हैं। डिफ़ॉल्ट रूप से, Javadoc उस निर्देशिका में HTML दस्तावेज़ीकरण फ़ाइलें उत्पन्न करेगा जहाँ आप कमांड दर्ज करते हैं। उपलब्ध विशिष्ट आदेशों पर सहायता प्राप्त करने के लिए बस दर्ज करें:

जावाडोक --मदद करना

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

जावाडोक ~/code/फ़ाइल नाम.जावा
जावाडोक ~/code/*।जावा

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

अपने नए बनाए गए दस्तावेज़ देखने के लिए, बस खोलें index.html अपने पसंदीदा ब्राउज़र में फ़ाइल करें। आपको निम्न जैसा पेज मिलेगा:

यह आउटपुट प्रदर्शित करने के लिए एकल, लघु जावा वर्ग के लिए प्रलेखन है। हेडर वर्ग के नाम के साथ-साथ उसमें शामिल विधियों को भी दिखाता है। नीचे स्क्रॉल करने से प्रत्येक वर्ग विधियों की अधिक विस्तृत परिभाषाएँ सामने आती हैं।

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

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

प्रोग्रामर के लिए 8 सर्वश्रेष्ठ जावा ब्लॉग

आगे पढ़िए