जावाडोक
जावाडोक जावा सोर्स कोड से एचटीएमएल प्रारूप में एपीआई प्रलेख तैयार करने के लिए जावा लेंग्वेज (अब ओरेकल कॉर्पोरेशन के स्वामित्व में) के लिए सन माइक्रोसिस्टम्स द्वारा बनाया गया एक प्रलेख जनरेटर है। एचटीएमएल प्रारूप का उपयोग संबंधित प्रलेखों को एक साथ हाइपरलिंक करने में सक्षम होने की सुविधा जोड़ने के लिए किया जाता है।[1] [2] प्रलेख टिप्पणी प्रारूप[3] जावाडोक द्वारा उपयोग किया जाने वाला जावा क्लासेस के प्रलेखीकरण के लिए वास्तविक उद्योग मानक है। कुछ एकीकृत विकास वातावरण,[4] IntelliJ IDEA, नेटबीनस और इक्लिप्स (सॉफ़्टवेयर) की तरह, स्वचालित रूप से जावाडोक टेम्पलेट उत्पन्न करते हैं। कई फ़ाइल संपादक जावाडोक सोर्स तैयार करने में उपयोगकर्ता की सहायता करते हैं और प्रोग्रामर के लिए आंतरिक संदर्भ के रूप में जावाडोक जानकारी का उपयोग करते हैं।
जावाडोक डॉकलेट्स और टैगलेट बनाने के लिए एक एपीआई भी प्रदान करता है, जो उपयोगकर्ताओं को जावा एप्लिकेशन की संरचना का विश्लेषण करने की अनुमति देता है। इस प्रकार JDiff एक एपीआई के दो संस्करणों के बीच क्या बदलाव हुआ इसकी रिपोर्ट तैयार कर सकता है।
जावाडोक जावा में प्रदर्शन को प्रभावित नहीं करता है क्योंकि संकलन के समय सभी टिप्पणियाँ हटा दी जाती हैं। टिप्पणियाँ और जावाडोक लिखना कोड को बेहतर ढंग से समझने और इस प्रकार इसे बेहतर बनाए रखने के लिए है।
इतिहास
जावाडोक एक प्रारंभिक जावा लेंग्वेज प्रलेखीकरण जनरेटर था।[5] प्रलेखीकरण जनरेटर के उपयोग से पहले तकनीकी लेखकों का उपयोग करने की प्रथा थी जो सामान्यत: सॉफ़्टवेयर के लिए केवल स्टैंडअलोन प्रलेख लिखते थे,[6] लेकिन इस प्रलेख को सॉफ़्टवेयर के साथ समन्वयित रखना बहुत कठिन था।
जावा द्वारा पहली रिलीज़ के बाद से जावाडोक का उपयोग किया गया है, और सामान्यत: जावा डेवलपमेंट किट की हर नई रिलीज़ पर इसे अपडेट किया जाता है। @फील्ड जावाडोक के सिंटैक्स का अनुकरण अन्य लेंग्वेजओं के लिए प्रलेखीकरण प्रणालियों द्वारा किया गया है, जिसमें क्रॉस-लैंग्वेज डॉक्सिजन, जावास्क्रिप्ट के लिए जेएसडॉक सिस्टम और ऐप्पल के हेडरडॉक सम्मलित हैं।
तकनीकी वास्तुकला
जावाडोक टिप्पणी की संरचना
जावाडोक टिप्पणी को मानक बहु लाइन टिप्पणी टैग द्वारा कोड से अलग किया जाता है /* और */. आरंभिक टैग (जिसे आरंभ-टिप्पणी सीमांकक कहा जाता है) में एक अतिरिक्त तारांकन चिह्न होता है /**.
- पहला पैराग्राफ प्रलेखित विधि का विवरण है।
- विवरण के बाद अलग-अलग संख्या में वर्णनात्मक टैग हैं, जो दर्शाते हैं:
- विधि के पैरामीटर (
@param) - विधि क्या लौटाती है (
@return) - कोई भी अपवाद जो विधि फेंक सकती है (
@throws) - अन्य कम-सामान्य टैग जैसे
@see(टैग भी देखें)
- विधि के पैरामीटर (
जावाडोक का अवलोकन
प्रलेख टिप्पणियाँ लिखने की मूल संरचना उन्हें अंदर एम्बेड करना है।
/** ... */. जावाडोक टिप्पणी ब्लॉक आइटम के ठीक ऊपर स्थित है
बिना किसी अलग नई लाइन के ध्यान दें कि कोई भी आयात विवरण वर्ग घोषणा से पहले होना चाहिए। वर्ग घोषणा में सामान्यत: सम्मलित होते हैं:
// import statements
/**
* @author Firstname Lastname <address @ example.com>
* @version 1.6 (current version number of program)
* @since 1.2 (the version of the package this class was first added to)
*/
public class Test {
// class body
}
विधियों के लिए (1) एक संक्षिप्त, संक्षिप्त, एक पंक्ति का विवरण है
बताएं कि आइटम क्या करता है. इसके बाद (2) एक लंबा समय आता है
विवरण जो कई अनुच्छेदों तक फैला हो सकता है। विवरण
यहाँ पूर्ण रूप से समझाया जा सकता है। यह अनुभाग है
वैकल्पिक, अंत में, स्वीकृत इनपुट को सूचीबद्ध करने के लिए (3) एक टैग अनुभाग है
विधि के तर्क और वापसी मान ध्यान दें कि सभी
जावाडोक को एचटीएमएल के रूप में माना जाता है इसलिए एकाधिक पैराग्राफ अनुभाग
द्वारा अलग किए गए हैं<p>पैराग्राफ़ ब्रेक टैग।
/**
* Short one line description. (1)
* <p>
* Longer description. If there were any, it would be (2)
* here.
* <p>
* And even more explanations to follow in consecutive
* paragraphs separated by HTML paragraph breaks.
*
* @param variable Description text text text. (3)
* @return Description text text text.
*/
public int methodName (...) {
// method body with a return statement
}
वेरीयेबल को अपवाद के साथ विधियों के समान ही प्रलेखित किया जाता है भाग (3) हटा दिया गया है। यहां वेरिएबल में केवल लघु सम्मलित है विवरण:
/**
* Description of the variable here.
*/
private int debug = 0;
ध्यान दें कि यह अनुशंसित नहीं है[7] एक प्रलेखीकरण टिप्पणी में एकाधिक वेरीयेबल परिभाषित करने के लिए है। ऐसा इसलिए है क्योंकि जावाडोक प्रत्येक वेरिएबल को पढ़ता है और उन्हें समान प्रलेख टिप्पणी के साथ जेनरेट किए गए एचटीएमएल पृष्ठ पर अलग-अलग रखता है जिसे सभी फ़ील्ड के लिए कॉपी किया जाता है।
/**
* The horizontal and vertical distances of point (x,y)
*/
public int x, y; // AVOID
इसके अतिरिक्त, प्रत्येक वेरीयेबल को अलग से लिखने और प्रलेखित करने की अनुशंसा की जाती है:
/**
* The horizontal distance of point.
*/
public int x;
/**
* The vertical distance of point.
*/
public int y;
जावाडोक टैग की तालिका
कुछ उपलब्ध जावाडोक टैग[8] नीचे दी गई तालिका में सूचीबद्ध हैं:
| टैग एवं पैरामीटर | प्रयोग | लागू होता है | तब से |
|---|---|---|---|
| @author जॉन स्मिथ | एक लेखक का वर्णन करता है। | क्लास, इंटरफ़ेस, एनम | |
| {@docRoot} | किसी भी जेनरेट किए गए पेज से जेनरेट किए गए प्रलेख की रूट निर्देशिका के सापेक्ष पथ का प्रतिनिधित्व करता है। | क्लास, इंटरफ़ेस, एनम, फील्ड, मैथड | |
| @version संस्करण | सॉफ़्टवेयर संस्करण प्रविष्टि प्रदान करता है. प्रति क्लास या इंटरफ़ेस अधिकतम एक। | क्लास, इंटरफ़ेस, एनम | |
| @since सिन्स-टेक्सट | वर्णन करता है कि यह कार्यक्षमता पहली बार कब अस्तित्व में थी। | क्लास, इंटरफ़ेस, एनम, फील्ड, मैथड | |
| @see संदर्भ | प्रलेखीकरण के अन्य तत्वों के लिए एक लिंक प्रदान करता है। | क्लास, इंटरफ़ेस, एनम, फील्ड, मैथड | |
| @param नाम विवरण | एक मैथड पैरामीटर का वर्णन करता है। | मैथड | |
| @return विवरण | वापसी मान का वर्णन करता है. | मैथड | |
| @exception क्लासनाम विवरण @throws क्लासनाम विवरण |
एक अपवाद का वर्णन करता है जिसे इस गणित से निकाला जा सकता है। | मैथड | |
| @deprecated विवरण | एक पुराने मैथड का वर्णन करता है। | क्लास, इंटरफ़ेस, एनम, फील्ड, मैथड | |
| {@inheritDoc} | ओवरराइड मैथड से विवरण की प्रतिलिपि बनाएँ। | Overriding मैथड | 1.4.0 |
| {@link संदर्भ} | अन्य प्रतीक से लिंक करें। | क्लास, इंटरफ़ेस, एनम, फील्ड, मैथड | |
| {@linkplain संदर्भ} | {@link} के समान, सिवाय इसके कि लिंक का लेबल कोड फ़ॉन्ट की तुलना में सादे पाठ में प्रदर्शित होता है। | क्लास, इंटरफ़ेस, एनम, फील्ड, मैथड | |
| {@value #स्टैटिक_फील्ड} | स्थैतिक फ़ील्ड का मान लौटाएँ। | स्टैटिक फील्ड | 1.4.0 |
| {@code लिटरल} | कोड फ़ॉन्ट में शाब्दिक पाठ को प्रारूपित करता है। यह के बराबर है <code>{@लिटरल}</code>. | क्लास, इंटरफ़ेस, एनम, फील्ड, मैथड | 1.5.0 |
| {@लिटरल लिटरल} | शाब्दिक पाठ को दर्शाता है. संलग्न पाठ की व्याख्या इस प्रकार की गई है कि इसमें एचटीएमएल मार्कअप या नेस्टेड जावाडोक टैग सम्मलित नहीं हैं। | क्लास, इंटरफ़ेस, एनम, फील्ड, मैथड | 1.5.0 |
| {@serial लिटरल} | डिफ़ॉल्ट क्रमबद्ध फ़ील्ड के लिए प्रलेख टिप्पणी में उपयोग किया जाता है। | फील्ड | |
| {@serialData लिटरल} | राइटऑब्जेक्ट () या राइटएक्सटर्नल () मैथड द्वारा लिखे गए डेटा का दस्तावेजीकरण करें। | फील्ड, मैथड | |
| {@serialफील्ड लिटरल} | एक ऑब्जेक्टस्ट्रीमफ़ील्ड घटक का प्रलेखीकरण। | फील्ड |
उदाहरण
किसी विधि का प्रलेखीकरण करने के लिए जावाडोक का एक उदाहरण इस प्रकार है। ध्यान दें कि इस उदाहरण में रिक्ति और वर्णों की संख्या कन्वेंशन स्थिति के अनुसार है।
/**
* Validates a chess move.
*
* <p>Use {@link #doMove(int fromFile, int fromRank, int toFile, int toRank)} to move a piece.
*
* @param fromFile file from which a piece is being moved
* @param fromRank rank from which a piece is being moved
* @param toFile file to which a piece is being moved
* @param toRank rank to which a piece is being moved
* @return true if the move is valid, otherwise false
* @since 1.0
*/
boolean isValidMove(int fromFile, int fromRank, int toFile, int toRank) {
// ...body
}
/**
* Moves a chess piece.
*
* @see java.math.RoundingMode
*/
void doMove(int fromFile, int fromRank, int toFile, int toRank) {
// ...body
}
डॉकलेट्स
डॉकलेट प्रोग्राम जावा (प्रोग्रामिंग लेंग्वेज) में लिखे कोड से प्रलेख तैयार करने के लिए जावाडोक टूल के साथ काम करते हैं।[9]
डॉकलेट जावा प्रोग्रामिंग लेंग्वेज में लिखे गए हैं और इसका उपयोग करते हैं Doclet API को:
- प्रलेख में कौन सी सामग्री सम्मलित करनी है उसका चयन करें।
- सामग्री की प्रस्तुति को प्रारूपित करें।
- वह फ़ाइल बनाएं जिसमें प्रलेख सम्मलित हो वह
StandardDoclet[3] जावाडोक के साथ सम्मलित होकर फ्रेम-आधारित एचटीएमएल फ़ाइलों के रूप में एपीआई प्रलेख तैयार करता है। वेब पर कई गैर-मानक प्रलेख उपलब्ध हैं[citation needed], अधिकांशत: मुफ़्त में। इनका उपयोग इसके लिए किया जा सकता है। - अन्य गैर-एपीआई प्रकार के प्रलेख बनाएं।
- प्रलेख को पीडीएफ जैसे अन्य गैर-एचटीएमएल फ़ाइल प्रकारों में आउटपुट करें।
- खोज जैसी अतिरिक्त सुविधाओं के साथ या जावा क्लासेस से उत्पन्न एम्बेडेड एकीकृत मॉडलिंग लेंग्वेज आरेखों के साथ प्रलेख को एचटीएमएल के रूप में आउटपुट करें।
यह भी देखें
- प्रलेखीकरण जनरेटर की तुलना।
- सी शार्प सिंटैक्स#एक्सएमएल डॉक्यूमेंटेशन सिस्टम|नेट एक्सएमएल डॉक्यूमेंटेशन टिप्पणियाँ।
संदर्भ
- ↑ Now cased as 'Javadoc'. See [1]. Originally cased as 'JavaDoc'. See [2]
- ↑ "जावाडोक". agile.csc.ncsu.edu. Archived from the original on 13 June 2017. Retrieved 12 January 2022.
- ↑ "javadoc - जावा एपीआई दस्तावेज़ीकरण जेनरेटर". Sun Microsystems. Retrieved 2011-09-30..
- ↑ IntelliJ IDEA, NetBeans Archived 2017-04-05 at the Wayback Machine and Eclipse
- ↑ "Javadoc टूल के लिए दस्तावेज़ टिप्पणियाँ कैसे लिखें". Sun Microsystems. Retrieved 2011-09-30..
- ↑ Venners, Bill; Gosling, James; et al. (2003-07-08). "Visualizing with JavaDoc". artima.com. Retrieved 2013-01-19.
When I did the original JavaDoc in the original compiler, even the people close around me pretty soundly criticized it. And it was interesting, because the usual criticism was: a good tech writer could do a lot better job than the JavaDoc does. And the answer is, well, yeah, but how many APIs are actually documented by good tech writers? And how many of them actually update their documentation often enough to be useful?
- ↑ "Java Platform, Standard Edition Tools Reference for Oracle JDK on Solaris, Linux, and OS X, Release 8. Section "Multiple-Field Declarations"". Retrieved 20 Dec 2017.
- ↑ JavaSE 13 Documentation Comment Specification
- ↑ "Doclet Overview".
बाहरी संबंध
- Java Platform, Standard Edition जावाडोक Guide
- JSR 260 जावाडोक Tag Technology Update Java Specification Request (defines new जावाडोक tags)
- Improve on जावाडोक with ashkelon
- Globaldocs: A viewer to browse multiple जावाडोकs simultaneously.
- Various Java documentations converted to Windows Help format
