जावाडोक

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

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

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

इतिहास

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

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

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

Javadoc टिप्पणी की संरचना

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

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

जावाडोक का अवलोकन

दस्तावेज़ टिप्पणियाँ लिखने की मूल संरचना उन्हें अंदर एम्बेड करना है /** ... */. Javadoc टिप्पणी ब्लॉक आइटम के ठीक ऊपर स्थित है बिना किसी अलग नई लाइन के। ध्यान दें कि कोई भी आयात विवरण वर्ग घोषणा से पहले होना चाहिए। आमतौर पर वर्ग घोषणा रोकना:

// 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) एक टैग अनुभाग है विधि के तर्क और वापसी मान। ध्यान दें कि सभी Javadoc को HTML के रूप में माना जाता है इसलिए एकाधिक पैराग्राफ अनुभाग ए द्वारा अलग किए गए हैं<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;

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

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

Javadoc टैग की तालिका

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

Tag & Parameter	Usage	Applies to	Since
@author John Smith	Describes an author.	Class, Interface, Enum
{@docRoot}	Represents the relative path to the generated document's root directory from any generated page.	Class, Interface, Enum, Field, Method
@version version	Provides software version entry. Max one per Class or Interface.	Class, Interface, Enum
@since since-text	Describes when this functionality has first existed.	Class, Interface, Enum, Field, Method
@see reference	Provides a link to other element of documentation.	Class, Interface, Enum, Field, Method
@param name description	Describes a method parameter.	Method
@return description	Describes the return value.	Method
@exception classname description @throws classname description	Describes an exception that may be thrown from this method.	Method
@deprecated description	Describes an outdated method.	Class, Interface, Enum, Field, Method
{@inheritDoc}	Copies the description from the overridden method.	Overriding Method	1.4.0
{@link reference}	Link to other symbol.	Class, Interface, Enum, Field, Method
{@linkplain reference}	Identical to {@link}, except the link's label is displayed in plain text than code font.	Class, Interface, Enum, Field, Method
{@value #STATIC_FIELD}	Return the value of a static field.	Static Field	1.4.0
{@code literal}	Formats literal text in the code font. It is equivalent to <code>{@literal}</code>.	Class, Interface, Enum, Field, Method	1.5.0
{@literal literal}	Denotes literal text. The enclosed text is interpreted as not containing HTML markup or nested javadoc tags.	Class, Interface, Enum, Field, Method	1.5.0
{@serial literal}	Used in the doc comment for a default serializable field.	Field
{@serialData literal}	Documents the data written by the writeObject( ) or writeExternal( ) methods.	Field, Method
{@serialField literal}	Documents an ObjectStreamField component.	Field

उदाहरण

किसी विधि का दस्तावेज़ीकरण करने के लिए Javadoc का एक उदाहरण इस प्रकार है। ध्यान दें कि इस उदाहरण में रिक्ति और वर्णों की संख्या कन्वेंशन स्थिति के अनुसार है।

/**
 * 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] Javadoc के साथ शामिल होकर फ्रेम-आधारित HTML फ़ाइलों के रूप में API दस्तावेज़ तैयार करता है। वेब पर कई गैर-मानक दस्तावेज़ उपलब्ध हैं, अक्सर मुफ़्त में। इनका उपयोग इसके लिए किया जा सकता है:
• अन्य गैर-एपीआई प्रकार के दस्तावेज़ बनाएं
• दस्तावेज़ को पीडीएफ जैसे अन्य गैर-एचटीएमएल फ़ाइल प्रकारों में आउटपुट करें
• खोज जैसी अतिरिक्त सुविधाओं के साथ या जावा कक्षाओं से उत्पन्न एम्बेडेड एकीकृत मॉडलिंग भाषा आरेखों के साथ दस्तावेज़ को HTML के रूप में आउटपुट करें

यह भी देखें

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

बाहरी संबंध

• Java Platform, Standard Edition Javadoc Guide
• JSR 260 Javadoc Tag Technology Update Java Specification Request (defines new Javadoc tags)
• Improve on Javadoc with ashkelon
• Globaldocs: A viewer to browse multiple Javadocs simultaneously.
• Various Java documentations converted to Windows Help format