जावाडोक

जावाडोक (मूल रूप से जावाडोक का आवरण) जावा (प्रोग्रामिंग लेंग्वेज) स्रोत कोड से एचटीएमएल प्रारूप में अप्लिकेशन प्रोग्रामिंग अंतरफलक दस्तावेज़ तैयार करने के लिए जावा (प्रोग्रामिंग लेंग्वेज) (अब ओरेकल कॉर्पोरेशन के स्वामित्व में) के लिए सन माइक्रोसिस्टम्स द्वारा बनाया गया एक दस्तावेज़ जनरेटर है। एचटीएमएल प्रारूप का उपयोग संबंधित दस्तावेज़ों को एक साथ हाइपरलिंक करने में सक्षम होने की सुविधा जोड़ने के लिए किया जाता है। दस्तावेज़ टिप्पणी प्रारूप जावाडोक द्वारा उपयोग किया जाने वाला जावा क्लासेस के दस्तावेज़ीकरण के लिए वास्तविक उद्योग मानक है। कुछ एकीकृत विकास वातावरण, IntelliJ IDEA, नेटबीनस और इक्लिप्स (सॉफ़्टवेयर) की तरह, स्वचालित रूप से जावाडोक टेम्पलेट उत्पन्न करते हैं। कई फ़ाइल संपादक जावाडोक स्रोत तैयार करने में उपयोगकर्ता की सहायता करते हैं और प्रोग्रामर के लिए आंतरिक संदर्भ के रूप में जावाडोक जानकारी का उपयोग करते हैं।

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

जावाडोक जावा में प्रदर्शन को प्रभावित नहीं करता है क्योंकि संकलन के समय सभी टिप्पणियाँ हटा दी जाती हैं। टिप्पणियाँ और जावाडोक लिखना कोड को बेहतर ढंग से समझने और इस प्रकार इसे बेहतर बनाए रखने के लिए है।

इतिहास

जावाडोक एक प्रारंभिक जावा लेंग्वेज दस्तावेज़ीकरण जनरेटर था। दस्तावेज़ीकरण जनरेटर के उपयोग से पहले तकनीकी लेखकों का उपयोग करने की प्रथा थी जो सामान्यत: सॉफ़्टवेयर के लिए केवल स्टैंडअलोन दस्तावेज़ लिखते थे, लेकिन इस दस्तावेज़ को सॉफ़्टवेयर के साथ समन्वयित रखना बहुत कठिन था।

जावा द्वारा पहली रिलीज़ के बाद से जावाडोक का उपयोग किया गया है, और सामान्यत: जावा डेवलपमेंट किट की हर नई रिलीज़ पर इसे अपडेट किया जाता है। @फील्ड जावाडोक के सिंटैक्स का अनुकरण अन्य लेंग्वेजओं के लिए दस्तावेज़ीकरण प्रणालियों द्वारा किया गया है, जिसमें क्रॉस-लैंग्वेज डॉक्सिजन, जावास्क्रिप्ट के लिए जेएसडॉक सिस्टम और ऐप्पल के हेडरडॉक सम्मलित हैं।

तकनीकी वास्तुकला

जावाडोक टिप्पणी की संरचना

जावाडोक टिप्पणी को मानक बहु लाइन टिप्पणी टैग द्वारा कोड से अलग किया जाता है /* और */. आरंभिक टैग (जिसे आरंभ-टिप्पणी सीमांकक कहा जाता है) में एक अतिरिक्त तारांकन चिह्न होता है /**.

1. पहला पैराग्राफ प्रलेखित विधि का विवरण है।
2. विवरण के बाद अलग-अलग संख्या में वर्णनात्मक टैग हैं, जो दर्शाते हैं:
   1. विधि के पैरामीटर (@param)
   2. विधि क्या लौटाती है (@return)
   3. कोई भी अपवाद जो विधि फेंक सकती है (@throws)
   4. अन्य कम-सामान्य टैग जैसे @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;

ध्यान दें कि यह अनुशंसित नहीं है एक दस्तावेज़ीकरण टिप्पणी में एकाधिक चर परिभाषित करने के लिए है। ऐसा इसलिए है क्योंकि जावाडोक प्रत्येक वेरिएबल को पढ़ता है और उन्हें समान दस्तावेज़ टिप्पणी के साथ जेनरेट किए गए एचटीएमएल पृष्ठ पर अलग-अलग रखता है जिसे सभी फ़ील्ड के लिए कॉपी किया जाता है।

/**
 * 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;

जावाडोक टैग की तालिका

कुछ उपलब्ध जावाडोक टैग नीचे दी गई तालिका में सूचीबद्ध हैं:

टैग एवं पैरामीटर	प्रयोग	लागू होता है	तब से
@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
}

डॉकलेट्स

डॉकलेट प्रोग्राम जावा (प्रोग्रामिंग लेंग्वेज) में लिखे कोड से दस्तावेज़ तैयार करने के लिए जावाडोक टूल के साथ काम करते हैं। डॉकलेट जावा प्रोग्रामिंग लेंग्वेज में लिखे गए हैं और इसका उपयोग करते हैं Doclet API को:

• दस्तावेज़ में कौन सी सामग्री सम्मलित करनी है उसका चयन करें।
• सामग्री की प्रस्तुति को प्रारूपित करें।
• वह फ़ाइल बनाएं जिसमें दस्तावेज़ सम्मलित हो वह StandardDoclet[3] जावाडोक के साथ सम्मलित होकर फ्रेम-आधारित एचटीएमएल फ़ाइलों के रूप में एपीआई दस्तावेज़ तैयार करता है। वेब पर कई गैर-मानक दस्तावेज़ उपलब्ध हैं, अधिकांशत: मुफ़्त में। इनका उपयोग इसके लिए किया जा सकता है।
• अन्य गैर-एपीआई प्रकार के दस्तावेज़ बनाएं।
• दस्तावेज़ को पीडीएफ जैसे अन्य गैर-एचटीएमएल फ़ाइल प्रकारों में आउटपुट करें।
• खोज जैसी अतिरिक्त सुविधाओं के साथ या जावा क्लासेस से उत्पन्न एम्बेडेड एकीकृत मॉडलिंग लेंग्वेज आरेखों के साथ दस्तावेज़ को एचटीएमएल के रूप में आउटपुट करें।

यह भी देखें

• दस्तावेज़ीकरण जनरेटर की तुलना।
• सी शार्प सिंटैक्स#एक्सएमएल डॉक्यूमेंटेशन सिस्टम|नेट एक्सएमएल डॉक्यूमेंटेशन टिप्पणियाँ।

बाहरी संबंध

• 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