what is javadoc how use it generate documentation
यह ट्यूटोरियल बताता है कि JavaDoc टूल और JavaDoc टिप्पणियाँ और कोड प्रलेखन उत्पन्न करने के तरीके क्या हैं:
JavaDoc एक विशेष उपकरण है जिसे JDK के साथ पैक किया गया है। इसका उपयोग HTML फॉर्मेट में जावा सोर्स कोड के कोड डॉक्यूमेंट जनरेट करने के लिए किया जाता है।
यह सन माइक्रोसिस्टम्स (वर्तमान में ओरेकल कॉर्पोरेशन) से जावा भाषा के लिए एक प्रलेखन जनरेटर है।
=> यहाँ सभी जावा ट्यूटोरियल की जाँच करें।
आप क्या सीखेंगे:
JavaDoc क्या है
यह उपकरण जावा कक्षाओं के दस्तावेज़ के लिए 'डॉक्टर टिप्पणियों' प्रारूप का उपयोग करता है। Eclipse, IntelliJIDEA या NetBeans जैसी IDE में HTML डॉक्यूमेंट जनरेट करने के लिए एक इन-बिल्ट जावाडॉक टूल है। हमारे पास बाजार में कई फ़ाइल संपादक भी हैं जो प्रोग्रामर को JavaDoc स्रोतों का उत्पादन करने में मदद कर सकते हैं।
स्रोत कोड प्रलेखन के अलावा यह उपकरण एपीआई भी प्रदान करता है जो 'डॉकलेट्स' और 'टैगलेट्स' बनाता है जिसका उपयोग हम एक जावा एप्लिकेशन की संरचना का विश्लेषण करने के लिए करते हैं।
ध्यान देने वाली बात यह है कि यह उपकरण किसी भी तरह से एप्लिकेशन के प्रदर्शन को प्रभावित नहीं करता है क्योंकि कंपाइलर जावा प्रोग्राम के संकलन के दौरान सभी टिप्पणियों को हटा देता है।
प्रोग्राम में टिप्पणियाँ लिखना और फिर प्रलेखन उत्पन्न करने के लिए JavaDoc का उपयोग करके प्रोग्रामर / उपयोगकर्ता को कोड को समझने में मदद करना है।
जावा डॉक्यूमेंट द्वारा तैयार HTML डॉक्यूमेंट API डॉक्यूमेंटेशन है यह घोषणाओं को पार्स करता है और स्रोत फ़ाइलों का एक सेट उत्पन्न करता है। स्रोत फ़ाइल फ़ील्ड, विधियों, कंस्ट्रक्टर और कक्षाओं का वर्णन करती है।
ध्यान दें कि इससे पहले कि हम अपने सोर्स कोड पर JavaDoc टूल का उपयोग करें, हमें प्रोग्राम में विशेष JavaDoc टिप्पणियों को शामिल करना चाहिए।
अब टिप्पणियों पर चलते हैं।
JavaDoc टिप्पणियाँ
जावा भाषा निम्नलिखित प्रकार की टिप्पणियों का समर्थन करती है।
(1) एकल पंक्ति टिप्पणियाँ: एकल-पंक्ति टिप्पणी 'द्वारा निरूपित की जाती है' // 'और जब कंपाइलर का सामना इनसे होता है, तो यह उन सभी बातों को नजरअंदाज कर देता है जो इन टिप्पणियों को लाइन के अंत तक फॉलो करती हैं।
# 2) बहुभाषी टिप्पणियां: बहुस्तरीय टिप्पणियों का उपयोग करके प्रतिनिधित्व किया जाता है ” /* ”। इसलिए ‘/ * अनुक्रम का सामना करने पर, कंपाइलर इस क्रम का पालन करने वाले सभी चीजों को अनदेखा करता है, जब तक कि यह समापन अनुक्रम closing * / से सामना नहीं करता है।
# 3) प्रलेखन टिप्पणियाँ: इन्हें डॉक कॉमेंट्स कहा जाता है और इनका इस्तेमाल एपीआई डॉक्यूमेंट जेनरेट करने के लिए टूल द्वारा किया जाता है। डॉक्टर की टिप्पणियों को ' / ** प्रलेखन * / ”। जैसा कि हम देख सकते हैं, ये टिप्पणियां ऊपर वर्णित सामान्य टिप्पणियों से अलग हैं। डॉक्स टिप्पणियों में उनके अंदर HTML टैग भी हो सकते हैं जैसा कि हम शीघ्र ही देखेंगे।
काम में कठिन परिस्थितियों से निपटना
इसलिए इस टूल का उपयोग करके API डॉक्यूमेंटेशन जेनरेट करने के लिए, हमें अपने प्रोग्राम में इन डॉक्यूमेंट कमेंट्स (डॉक कमेंट्स) को उपलब्ध कराना होगा।
एक जावाडॉक टिप्पणी की संरचना
जावा में डॉक टिप्पणी की संरचना बहुस्तरीय टिप्पणी के समान है, सिवाय इसके कि डॉक टिप्पणी में शुरुआती टैग में एक अतिरिक्त तारांकन (*) है। इसलिए डॉक्टर की टिप्पणी * / * के बजाय ’/ **’ से शुरू होती है।
इसके अतिरिक्त, JavaDoc शैली टिप्पणियों में इसके अंदर HTML टैग भी हो सकते हैं।
JavaDoc टिप्पणी प्रारूप
उस प्रोग्रामिंग कंस्ट्रक्शन के आधार पर, जिस पर हम दस्तावेज़ बनाना चाहते हैं, हम क्लास, मेथड, फील्ड आदि जैसे किसी भी निर्माण के ऊपर डॉक कमेंट्स रख सकते हैं। आइए, प्रत्येक कंस्ट्रक्ट्स के डॉक कॉमेंट्स के उदाहरणों के माध्यम से जाने दें।
कक्षा स्तर प्रारूप
कक्षा स्तर पर डॉक टिप्पणी प्रारूप नीचे दिखाया गया है:
/** * Mechanic * * Please see the {@link sth.javadoctutes.Person} class for true identity * @author SoftwareTestingHelp * */ public class Mechanic extends Person { // fields and methods } जैसा कि ऊपर दिखाया गया है, एक क्लास-स्तरीय डॉक्टर टिप्पणी में कक्षा के लेखक, लिंक यदि कोई हो, आदि सहित सभी विवरण होंगे।
विधि स्तर प्रारूप
नीचे दिए गए विधि स्तर पर डॉक्टर प्रारूप का एक उदाहरण है।
/** * simple method description … * JavaDoc! *
* @param msg the message to be printed * @return void * @see JavaDoc * @since 2.0 */ public void printMessage (String msg) { // do things return 0; } जैसा कि हम उपरोक्त उदाहरण से देख सकते हैं, हमारे पास विधि की डॉक टिप्पणी में कोई भी टैग हो सकते हैं। हमारे द्वारा इंगित टिप्पणी विवरण के अंदर पैराग्राफ भी हो सकते हैं
...
।हमारे पास रिटर्न टैग (@return) और विधि के मापदंडों (@param) का वर्णन करने के लिए विशेष टैग भी हैं।
फ़ील्ड स्तर प्रारूप
निम्न उदाहरण एक क्षेत्र के लिए डॉक्टर टिप्पणी दिखाता है।
/** * The public name of a message */ private String msg_txt;जैसा कि ऊपर दिए गए उदाहरण से देखा गया है, हम बिना किसी टैग के भी स्पष्ट टिप्पणी कर सकते हैं। ध्यान दें कि जब तक हम JavaDoc कमांड के साथ एक निजी विकल्प निर्दिष्ट नहीं करते हैं, तब तक JavaDoc निजी क्षेत्रों के लिए कोई दस्तावेज नहीं तैयार करता है।
अब उन टैग्स पर चर्चा करते हैं जो डॉक टिप्पणियों के साथ उपयोग किए जाते हैं।
JavaDoc टैग
जावा विभिन्न टैग प्रदान करता है जिन्हें हम डॉक्टर टिप्पणी में शामिल कर सकते हैं। जब हम इन टैग का उपयोग करते हैं, तो उपकरण इन टैग को स्रोत कोड से एक अच्छी तरह से स्वरूपित एपीआई बनाने के लिए पार्स करता है।
प्रत्येक टैग केस-संवेदी होता है और sign @ 'चिन्ह से शुरू होता है। प्रत्येक टैग लाइन की शुरुआत में शुरू होता है जैसा कि हम उपरोक्त उदाहरणों से देख सकते हैं। अन्यथा, संकलक इसे एक सामान्य पाठ के रूप में मानता है। एक सम्मेलन के रूप में, एक ही टैग को एक साथ रखा गया है।
दो प्रकार के टैग हैं जिनका उपयोग हम doc टिप्पणी में कर सकते हैं।
# 1) ब्लॉक टैग : ब्लॉक टैग का रूप है @टैग नाम ।
ब्लॉक टैग को टैग अनुभाग में रखा जा सकता है और मुख्य विवरण का पालन कर सकते हैं ।
# 2) इनलाइन टैग :इनलाइन टैग घुंघराले ब्रेसिज़ में संलग्न हैं और फॉर्म के हैं, {@टैग नाम} । इनलाइन टैग को डॉक्टर टिप्पणी के अंदर कहीं भी रखा जा सकता है।
निम्न तालिका उन सभी टैगों को सूचीबद्ध करती है जो डॉक्टर टिप्पणियों में उपयोग किए जा सकते हैं।
| टैग | विवरण | पर लागू होता है |
|---|---|---|
| @ विवरण का वर्णन करें | रिटर्न वैल्यू विवरण प्रदान करता है। | तरीका |
| @ कथोर xyz | वर्ग, इंटरफ़ेस, या enum के लेखक को इंगित करता है। | क्लास, इंटरफ़ेस, एनम |
| {@docRoot} | इस टैग में दस्तावेज़ की रूट निर्देशिका के सापेक्ष पथ है। | क्लास, इंटरफ़ेस, एनम, फील्ड, विधि |
| @ संस्करण | सॉफ़्टवेयर संस्करण प्रविष्टि निर्दिष्ट करता है। | क्लास, इंटरफ़ेस, एनम |
| @ के बाद से पाठ | निर्दिष्ट करता है कि कब से यह कार्यक्षमता मौजूद है | क्लास, इंटरफ़ेस, एनम, फील्ड, विधि |
| @ संदर्भ | अन्य प्रलेखन के लिए संदर्भ (लिंक) निर्दिष्ट करता है | क्लास, इंटरफ़ेस, एनम, फील्ड, विधि |
| @पाराम नाम विवरण | विधि पैरामीटर / तर्क का वर्णन करने के लिए उपयोग किया जाता है। | तरीका |
| @exception classname विवरण | अपवाद निर्दिष्ट करता है कि विधि अपने कोड में फेंक सकती है। | तरीका |
| @ क्लास का विवरण वर्णन करता है | ||
| @deprecated विवरण | निर्दिष्ट करता है कि क्या विधि पुरानी है | क्लास, इंटरफ़ेस, एनम, फील्ड, विधि |
| {@inheritDoc} | उत्तराधिकार के मामले में ओवरराइड विधि से विवरण की प्रतिलिपि बनाने के लिए उपयोग किया जाता है | ओवरराइडिंग विधि |
| {@ @ संदर्भ} | अन्य प्रतीकों को संदर्भ या लिंक प्रदान करता है। | क्लास, इंटरफ़ेस, एनम, फील्ड, विधि |
| {@linkplain संदर्भ} | {@Link} के समान लेकिन सादे पाठ में प्रदर्शित किया जाता है। | क्लास, इंटरफ़ेस, एनम, फील्ड, विधि |
| {@value #STATIC_FIELD} | स्थिर क्षेत्र का मान बताइए। | स्थैतिक क्षेत्र |
| {@ शाब्दिक} | {@Literal} के समान कोड फ़ॉन्ट में शाब्दिक पाठ को प्रारूपित करने के लिए प्रयुक्त। | Class, Interface, Enum, Field, Method |
| {@literal literal} | Indicates literal text. the enclosed text is interpreted literally without any style formatting. | Class, Interface, Enum, Field, Method |
| {@serial literal} | Description of a serializable field. | Field |
| {@serialData literal} | Documents the data written by the writeExternal( ) or writeObject( ) methods. | Field, Method |
| {@serialField literal} | Describes an ObjectStreamField component. | Field |
Generate Java Doc
To create a JavaDoc you do not need to compile the Java file. We can generate JavaDoc documentation in two ways.
#1) Using JavaDoc Command Via Command Line
The command-line tool allows us to run the command through it.
This command can be executed on a command line and has the following syntax.
user@sth:~$javadoc –d doc src*
In the above command, we assume that all the files and Java classes are in the src folder. Also, the documentation will be generated in the specified ‘doc’ directory.
Note that running the “javadoc” command without any parameters or flags results in an error.
विंडोज़ 10 के लिए फ्रीवेयर रजिस्ट्री क्लीनर
#2) Using The Tool From Any Of The Java IDEs.
All the major Java IDEs provide built-in functionality of generating documentation using the JavaDoc tool.
Using this built-in functionality is easier and also recommended than using a command-line tool to generate Java documentation.
Using JavaDoc With IntelliJIdea
Let’s generate documentation for a simple program using IntelliJIdea IDE.
We will consider the following program for which we have provided doc comments.
/** * Main class * * Please see the {@link www.softwaretestinghelp.com} class for true identity * @author SoftwareTestingHelp * */ public class Main{ /** * main method description … * JavaDoc! *
* @param args() string array * @return void * @see JavaDoc * */ public static void main(String args()) { System.out.println('Hello,World!!'); } } हम जानते हैं कि हमें JavaDoc उत्पन्न करने के लिए प्रोग्राम या प्रोजेक्ट को संकलित करने की आवश्यकता नहीं है। IntelliJIdea Ide प्रलेखन उत्पन्न करने के लिए एक अंतर्निहित टूल प्रदान करता है। IntelliJIdea का उपयोग करके प्रलेखन उत्पन्न करने के लिए नीचे दिए गए चरणों का पालन करें।
- Tools पर क्लिक करें -> JavaDoc जनरेट करें
- JavaDoc टूल को क्लिक करने पर निम्न स्क्रीन खुल जाती है।
यहां हम यह निर्दिष्ट कर सकते हैं कि क्या हम पूरी परियोजना या केवल एक वर्ग आदि के लिए दस्तावेज तैयार करना चाहते हैं। हम आउटपुट निर्देशिका को भी निर्दिष्ट कर सकते हैं जहां प्रलेखन फाइलें उत्पन्न होंगी। उपरोक्त आंकड़े में दिखाए गए अनुसार कई अन्य विनिर्देश हैं।
सभी पैरामीटर निर्दिष्ट किए जाने के बाद ठीक पर क्लिक करें।
- अब हम आउटपुट विंडो में Java Doc जनरेशन प्रोसेस देख सकते हैं। एक नमूना जावा डॉक आउटपुट विंडो नीचे दिखाया गया है:
- एक बार जब पीढ़ी पूरी हो जाती है, तो निम्न फाइलें उत्पन्न होती हैं।
- जैसा कि हमने मुख्य वर्ग को निर्दिष्ट किया है, फ़ाइल Main.html उत्पन्न होती है। ध्यान दें कि index.html में Main.html जैसी ही सामग्री है।
- फ़ाइल help-doc.html में जावा इकाइयाँ की सामान्य परिभाषाएँ हैं। इस फ़ाइल की सामग्री का एक नमूना नीचे दिखाया गया है।
- इसी तरह, नीचे दी गई फ़ाइल Main.html में एक नमूना सामग्री है
इस प्रकार, यह वह तरीका है जिसमें हम IntelliJ विचार में इस उपकरण का उपयोग करके प्रलेखन उत्पन्न कर सकते हैं। हम अन्य जावा IDEs जैसे ग्रहण और / या NetBeans में समान चरणों का पालन कर सकते हैं।
बार बार पूछे जाने वाले प्रश्न
Q # 1) JavaDoc का उपयोग क्या है?
उत्तर: JavaDoc टूल JDK के साथ आता है। यह HTML प्रारूप में जावा स्रोत कोड के लिए कोड प्रलेखन उत्पन्न करने के लिए उपयोग किया जाता है। इस उपकरण के लिए आवश्यक है कि स्रोत कोड में टिप्पणियों को पूर्वनिर्धारित प्रारूप में /**……*/ के रूप में प्रदान किया जाए। इन्हें डॉक कमेंट भी कहा जाता है।
Q # 2) जावा प्रलेखन उदाहरण क्या है?
उत्तर: जावा डॉक डॉक्यूमेंटेशन टूल HTML फाइल जेनरेट करता है ताकि हम वेब ब्राउजर से डॉक्यूमेंटेशन देख सकें। JavaDoc प्रलेखन का वास्तविक जीवंत उदाहरण Oracle Corporation, http://download.oracle.com/jav/// पर जावा पुस्तकालयों के लिए प्रलेखन है। डॉक्स /आग/।
Q # 3) क्या निजी तरीकों को JavaDoc की आवश्यकता है?
उत्तर: नहीं। निजी क्षेत्र और विधियां केवल डेवलपर्स के लिए हैं। निजी तरीकों या फ़ील्ड्स के लिए दस्तावेज़ प्रदान करने में कोई तर्क नहीं है जो एंड-यूज़र के लिए सुलभ नहीं हैं। जावा डॉक भी निजी संस्थाओं के लिए प्रलेखन उत्पन्न नहीं करता है।
सबसे अच्छा रिमोट एक्सेस सॉफ्टवेयर क्या है
Q # 4) JavaDoc कमांड क्या है?
उत्तर: यह आदेश जावा स्रोत फ़ाइलों में घोषणाओं और डॉक्टर टिप्पणियों को पार्स करता है और सार्वजनिक और संरक्षित कक्षाओं, नेस्टेड वर्गों, कंस्ट्रक्टरों, विधियों, फ़ील्ड्स और इंटरफेस के लिए संबंधित HTML प्रलेखन पृष्ठ उत्पन्न करता है।
हालाँकि, JavaDoc निजी संस्थाओं और अनाम आंतरिक वर्गों के लिए प्रलेखन उत्पन्न नहीं करता है।
निष्कर्ष
इस ट्यूटोरियल ने JDK के साथ पैक किए गए JavaDoc टूल का वर्णन किया है जो HTML फॉर्मेट में जावा सोर्स कोड के लिए कोड डॉक्यूमेंट जनरेट करने के लिए उपयोगी है। हम जावा डॉक कमांड को कमांड टूल के माध्यम से निष्पादित करके या अधिकांश जावा आईडीई में उपलब्ध इन-बिल्ट जावाडॉक कार्यक्षमता का उपयोग करके प्रलेखन उत्पन्न कर सकते हैं।
हमने देखा कि कैसे हम प्रलेखन बनाने के लिए IntelliJIdea Java IDE के साथ टूल का उपयोग कर सकते हैं। ट्यूटोरियल ने विभिन्न टैग्स को भी समझाया जो कि डॉक्स टिप्पणियों के साथ उपयोग किए जा सकते हैं ताकि टूल स्रोत कोड से संबंधित सभी जानकारी का विवरण देने वाले उपयोगकर्ता के अनुकूल प्रलेखन उत्पन्न कर सके।
=> स्क्रैच से जावा जानने के लिए यहां जाएं।
अनुशंसित पाठ
- जावा बेसिक्स: जावा सिंटैक्स, जावा क्लास और कोर जावा कॉन्सेप्ट
- जावा परिनियोजन: जावा जार फाइल का निर्माण और निष्पादन
- जावा वर्चुअल मशीन: जावा एप्लीकेशन चलाने में JVM कैसे मदद करता है
- जावा ट्यूटोरियल फॉर बिगिनर्स: 100+ हैंड्स-ऑन जावा वीडियो ट्यूटोरियल
- जावा इंटेगर एंड जावा बिगइन्टेगर क्लास विद एग्जाम्पल्स
- जावा कंपोनेंट्स: जावा प्लेटफॉर्म, जेडीके, जेआरई, और जावा वर्चुअल मशीन
- पोस्टमैन में एपीआई डॉक्यूमेंटेशन कैसे बनाएं?