Java Language
जावा कोड का दस्तावेजीकरण

algorithm Android HTML javafx JavaScript MySQL Regular Expressions spring spring-boot SQL
खोज…


परिचय

जावा कोड के लिए प्रलेखन अक्सर जावाडॉक का उपयोग करके उत्पन्न होता है। जावा स्रोत कोड से HTML प्रारूप में एपीआई प्रलेखन उत्पन्न करने के उद्देश्य से सन माइक्रोसिस्टम्स द्वारा Javadoc बनाया गया था। HTML प्रारूप का उपयोग करने से संबंधित दस्तावेजों को हाइपरलिंक करने में सक्षम होने की सुविधा मिलती है।

वाक्य - विन्यास

  • / ** - एक वर्ग, क्षेत्र, विधि या पैकेज पर JavaDoc की शुरुआत
  • @author // क्लास, इंटरफ़ेस या एनम के लेखक का नाम बताने के लिए। यह आवश्यक है।
  • @version // उस वर्ग का संस्करण, इंटरफ़ेस या एनम। यह आवश्यक है। चेकआउट को भरने के लिए आप स्रोत नियंत्रण सॉफ़्टवेयर के लिए% I% या% G% जैसे मैक्रोज़ का उपयोग कर सकते हैं।
  • @ अपरम // एक विधि या एक रचनाकार के तर्कों (मापदंडों) को दिखाने के लिए। प्रत्येक पैरामीटर के लिए एक @param टैग निर्दिष्ट करें।
  • @ ग्रेटर्न // गैर-शून्य तरीकों के लिए रिटर्न प्रकार दिखाने के लिए।
  • @exception // दिखाता है कि किस अपवाद को विधि या कंस्ट्रक्टर से फेंका जा सकता है। MUST को पकड़ा जाने वाले अपवादों को यहां सूचीबद्ध किया जाना चाहिए। यदि आप चाहें, तो आप उन्हें भी शामिल कर सकते हैं, जिन्हें पकड़ने की आवश्यकता नहीं है, जैसे कि ArrayIndexOutOfBoundsException। प्रत्येक अपवाद के लिए एक @exception निर्दिष्ट करें जिसे फेंका जा सकता है।
  • @throws // @ अपवाद के रूप में भी।
  • @ // // एक विधि, क्षेत्र, वर्ग या पैकेज के लिंक। पैकेज के रूप में उपयोग करें। # कुछ का उपयोग करें।
  • @since // जब यह विधि, फ़ील्ड या वर्ग जोड़ा गया था। उदाहरण के लिए, jD.-8 जैसे वर्ग के लिए java.util.Optional <T> ।
  • @serial, @serialField, @serialData // का उपयोग सीरियलव्यूडर यूआईडी को दिखाने के लिए किया जाता है।
  • @deprecated // पदावनत के रूप में एक वर्ग, विधि या क्षेत्र को चिह्नित करने के लिए। उदाहरण के लिए, एक java.io.StringBufferInputStream होगा। मौजूदा वंचित वर्गों की एक पूरी सूची यहाँ देखें ।
  • {@link} // @ के समान, लेकिन कस्टम टेक्स्ट के साथ उपयोग किया जा सकता है: {@link #setDefaultCloseOperation (int closeOperation) अधिक जानकारी के लिए JFrame # setDefaultCloseOperation देखें।
  • {@linkplain} // {@link} के समान, लेकिन कोड फ़ॉन्ट के बिना।
  • {@code} // शाब्दिक कोड के लिए, जैसे कि HTML टैग। उदाहरण के लिए: {@code <html> </ html>}। हालांकि, यह एक मोनोसैप्ड फ़ॉन्ट का उपयोग करेगा। मोनोस्पेस फ़ॉन्ट के बिना एक ही परिणाम प्राप्त करने के लिए, {@literal} का उपयोग करें।
  • {@ लिटरल} // समान {@कोड}, लेकिन बिना मोनोपॉज फ़ॉन्ट के।
  • {@value} // एक स्थिर फ़ील्ड का मान दिखाता है: JFrame # EXIT_ON_CLOSE का मान {@value} है। या, आप एक निश्चित फ़ील्ड से लिंक कर सकते हैं: ऐप नाम का उपयोग करता है {@value AppConstants # APP_NAME}।
  • {@docRoot} // वर्तमान फ़ाइल के सापेक्ष JavaDoc HTML का रूट फ़ोल्डर। उदाहरण: <a href="ministr@@ococootoot/credits.html"> क्रेडिट </a>।
  • HTML की अनुमति है: <code> "Hi कुकीज़" .substring (3) </ code>।
  • * / - जावाडॉक घोषणा का अंत

टिप्पणियों

Javadoc JDK के साथ शामिल एक उपकरण है जो इन-कोड टिप्पणियों को HTML प्रलेखन में बदलने की अनुमति देता है। जावा एपीआई विनिर्देश जावाडॉक का उपयोग करके उत्पन्न किया गया था। 3-पार्टी पुस्तकालयों के अधिकांश प्रलेखन के लिए भी यही सच है।

कक्षा का प्रलेखन

सभी Javadoc टिप्पणियाँ एक ब्लॉक टिप्पणी के साथ शुरू होती हैं, जिसके बाद एक तारांकन चिह्न ( /** ) होता है और अंत में जब ब्लॉक टिप्पणी करता है ( */ )। वैकल्पिक रूप से, प्रत्येक पंक्ति मनमाने ढंग से व्हाट्सएप और एक एकल तारांकन के साथ शुरू हो सकती है; जब दस्तावेज़ीकरण फ़ाइलें जनरेट की जाती हैं, तो उन्हें अनदेखा कर दिया जाता है। 

/**
 * Brief summary of this class, ending with a period.
 *
 * It is common to leave a blank line between the summary and further details.
 * The summary (everything before the first period) is used in the class or package 
 * overview section.
 *
 * The following inline tags can be used (not an exhaustive list): 
 * {@link some.other.class.Documentation} for linking to other docs or symbols
 * {@link some.other.class.Documentation Some Display Name} the link's appearance can be 
 * customized by adding a display name after the doc or symbol locator
 * {@code code goes here} for formatting as code
 * {@literal <>[]()foo} for interpreting literal text without converting to HTML markup 
 * or other tags.
 *
 * Optionally, the following tags may be used at the end of class documentation 
 * (not an exhaustive list):
 *
 * @author John Doe
 * @version 1.0
 * @since 5/10/15
 * @see some.other.class.Documentation
 * @deprecated This class has been replaced by some.other.package.BetterFileReader
 * 
 * You can also have custom tags for displaying additional information.
 * Using the @custom.<NAME> tag and the -tag custom.<NAME>:htmltag:"context"
 * command line option, you can create a custom tag.
 *
 * Example custom tag and generation:
 * @custom.updated 2.0    
 * Javadoc flag: -tag custom.updated:a:"Updated in version:"
 * The above flag will display the value of @custom.updated under "Updated in version:"
 *
 */
public class FileReader {
}

Classes लिए उपयोग किए जाने वाले समान टैग और प्रारूप का उपयोग Enums और Interfaces लिए भी किया जा सकता है।

विधि प्रलेखन

सभी Javadoc टिप्पणियाँ एक ब्लॉक टिप्पणी के साथ शुरू होती हैं, जिसके बाद एक तारांकन चिह्न ( /** ) होता है और अंत में जब ब्लॉक टिप्पणी करता है ( */ )। वैकल्पिक रूप से, प्रत्येक पंक्ति मनमाने ढंग से व्हाट्सएप और एक एकल तारांकन के साथ शुरू हो सकती है; जब दस्तावेज़ीकरण फ़ाइलें जनरेट की जाती हैं, तो उन्हें अनदेखा कर दिया जाता है। 

/**
 * Brief summary of method, ending with a period.
 *
 * Further description of method and what it does, including as much detail as is 
 * appropriate.  Inline tags such as
 * {@code code here}, {@link some.other.Docs}, and {@literal text here} can be used.
 *
 * If a method overrides a superclass method, {@inheritDoc} can be used to copy the 
 * documentation
 * from the superclass method
 *
 * @param stream Describe this parameter.  Include as much detail as is appropriate
 *               Parameter docs are commonly aligned as here, but this is optional.
 *               As with other docs, the documentation before the first period is 
 *               used as a summary.
 *
 * @return Describe the return values.  Include as much detail as is appropriate
 *         Return type docs are commonly aligned as here, but this is optional.
 *         As with other docs, the documentation before the first period is used as a 
 *         summary.
 *
 * @throws IOException Describe when and why this exception can be thrown.
 *                     Exception docs are commonly aligned as here, but this is 
 *                     optional.
 *                     As with other docs, the documentation before the first period 
 *                     is used as a summary.
 *                     Instead of @throws, @exception can also be used.
 *
 * @since 2.1.0
 * @see some.other.class.Documentation
 * @deprecated  Describe why this method is outdated. A replacement can also be specified.
 */
public String[] read(InputStream stream) throws IOException {
    return null;
}

फील्ड डॉक्यूमेंटेशन

सभी Javadoc टिप्पणियाँ एक ब्लॉक टिप्पणी के साथ शुरू होती हैं, जिसके बाद एक तारांकन चिह्न ( /** ) होता है और अंत में जब ब्लॉक टिप्पणी करता है ( */ )। वैकल्पिक रूप से, प्रत्येक पंक्ति मनमाने ढंग से व्हाट्सएप और एक एकल तारांकन के साथ शुरू हो सकती है; जब दस्तावेज़ीकरण फ़ाइलें जनरेट की जाती हैं, तो उन्हें अनदेखा कर दिया जाता है। 

/**
 * Fields can be documented as well.
 * 
 * As with other javadocs, the documentation before the first period is used as a
 * summary, and is usually separated from the rest of the documentation by a blank 
 * line.
 * 
 * Documentation for fields can use inline tags, such as:
 * {@code code here}
 * {@literal text here}
 * {@link other.docs.Here}
 * 
 * Field documentation can also make use of the following tags:
 * 
 * @since 2.1.0
 * @see some.other.class.Documentation
 * @deprecated Describe why this field is outdated
 */
public static final String CONSTANT_STRING = "foo";

पैकेज प्रलेखन

जावा एसई 5

यह एक फ़ाइल कहा जाता है का उपयोग कर Javadocs में पैकेज स्तरीय प्रलेखन बनाने के लिए संभव है package-info.java । इस फ़ाइल को नीचे के रूप में स्वरूपित किया जाना चाहिए। वैकल्पिक रूप से स्वरूपण के लिए प्रत्येक पंक्ति में मुख्य रूप से मौजूद व्हाट्सएप और तारांकन 

/**
 * Package documentation goes here; any documentation before the first period will 
 * be used as a summary.
 *
 * It is common practice to leave a blank line between the summary and the rest
 * of the documentation; use this space to describe the package in as much detail
 * as is appropriate.
 * 
 * Inline tags such as {@code code here}, {@link reference.to.other.Documentation},
 * and {@literal text here} can be used in this documentation.
 */
package com.example.foo;

// The rest of the file must be empty.

उपरोक्त मामले में, आपको जावा पैकेज com.example.foo के फ़ोल्डर के अंदर यह फ़ाइल package-info.java डालना होगा।

लिंक

अन्य Javadocs से लिंक करना @link टैग के साथ किया जाता है: 

/**
 * You can link to the javadoc of an already imported class using {@link ClassName}.
 *
 * You can also use the fully-qualified name, if the class is not already imported: 
 *  {@link some.other.ClassName}
 *
 * You can link to members (fields or methods) of a class like so:
 *  {@link ClassName#someMethod()}
 *  {@link ClassName#someMethodWithParameters(int, String)}
 *  {@link ClassName#someField}
 *  {@link #someMethodInThisClass()} - used to link to members in the current class
 *  
 * You can add a label to a linked javadoc like so:
 *  {@link ClassName#someMethod() link text} 
 */

पहले उदाहरण का स्क्रीन कैप्चर

@see टैग के साथ आप तत्वों को भी देखें अनुभाग में जोड़ सकते हैं। @return या @param @return की तरह जहां वे दिखाई देते हैं वह प्रासंगिक नहीं है। युक्ति कहती है आपको इसे @return बाद लिखना चाहिए। 

/**
 * This method has a nice explanation but you might found further
 * information at the bottom.
 *
 * @see ClassName#someMethod()
 */

उदाहरण के स्क्रीन पर कब्जा

यदि आप बाहरी संसाधनों से लिंक जोड़ना चाहते हैं तो आप बस HTML <a> टैग का उपयोग कर सकते हैं। आप इसे इनलाइन कहीं भी या दोनों के अंदर उपयोग कर सकते हैं @link और @see टैग। 

/**
 * Wondering how this works? You might want
 * to check this <a href="http://stackoverflow.com/">great service</a>.
 *
 * @see <a href="http://stackoverflow.com/">Stack Overflow</a>
 */

बाहरी लिंक उदाहरण का स्क्रीन कैप्चर

कमांड लाइन से Javadocs का निर्माण

कई आईडीई स्वचालित रूप से जावास्क्रिप्ट से HTML उत्पन्न करने के लिए समर्थन प्रदान करते हैं; कुछ बिल्ड टूल ( मावेन और ग्रेडल , उदाहरण के लिए) में प्लगइन्स भी हैं जो HTML निर्माण को संभाल सकते हैं।

हालाँकि, ये उपकरण Javadoc HTML उत्पन्न करने के लिए आवश्यक नहीं हैं; यह कमांड लाइन javadoc टूल का उपयोग करके किया जा सकता है।

उपकरण का सबसे बुनियादी उपयोग है: 

javadoc JavaFile.java

जो JavaFile.java में Javadoc टिप्पणियों से HTML उत्पन्न करेगा।

कमांड लाइन टूल का एक और अधिक व्यावहारिक उपयोग, जो [source-directory] में सभी जावा फ़ाइलों को पुन: पढ़ेगा, [package.name] और सभी उप-पैकेजों के लिए प्रलेखन बनाएँ, और उत्पन्न HTML को [docs-directory] है: 

javadoc -d [docs-directory] -subpackages -sourcepath [source-directory] [package.name]

इनलाइन कोड प्रलेखन

Javadoc प्रलेखन कोड के अलावा इनलाइन दस्तावेज किया जा सकता है।

सिंगल लाइन टिप्पणियां // द्वारा शुरू की जाती हैं और एक ही लाइन पर एक बयान के बाद पोस्ट की जा सकती हैं, लेकिन इससे पहले नहीं। 

public void method() {
  
  //single line comment
  someMethodCall(); //single line comment after statement
  
}

मल्टी-लाइन टिप्पणियों को /* और */ बीच परिभाषित किया गया है। वे कई पंक्तियों को फैला सकते हैं और बयानों के बीच भी लगाए जा सकते हैं। 

public void method(Object object) {
  
  /*
    multi 
    line 
    comment
  */
  object/*inner-line-comment*/.method(); 
}

JavaDocs मल्टी-लाइन टिप्पणियों का एक विशेष रूप है, जिसकी शुरुआत /** ।

चूंकि कई इनलाइन टिप्पणियां कोड की पठनीयता को कम कर सकती हैं, इसलिए कोड का स्व-व्याख्यात्मक नहीं होने या डिजाइन का निर्णय स्पष्ट नहीं होने की स्थिति में उनका उपयोग बहुत कम किया जाना चाहिए।

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

  • //TODO
  • //FIXME

या संदर्भ जारी करते हैं, यानी जीरा के लिए

  • //PRJ-1234

प्रलेखन के अंदर कोड स्निपेट

प्रलेखन के अंदर कोड लिखने का विहित तरीका {@code } निर्माण के साथ है। यदि आपके पास <pre></pre> अंदर मल्टीलाइन कोड रैप है। 

/**
 * The Class TestUtils.
 * <p>
 * This is an {@code inline("code example")}.
 * <p>
 * You should wrap it in pre tags when writing multiline code.
 * <pre>{@code
 *  Example example1 = new FirstLineExample();
 *  example1.butYouCanHaveMoreThanOneLine();
 * }</pre>
 * <p>
 * Thanks for reading.
 */
class TestUtils {

कभी-कभी आपको javadoc टिप्पणी के अंदर कुछ जटिल कोड डालने की आवश्यकता हो सकती है। @ चिह्न विशेष रूप से समस्याग्रस्त है। {@literal } साथ पुराने <code> टैग का उपयोग समस्या को हल करता है। 

/**
 * Usage:
 * <pre><code>
 * class SomethingTest {
 * {@literal @}Rule
 *  public SingleTestRule singleTestRule = new SingleTestRule("test1");
 *
 * {@literal @}Test
 *  public void test1() {
 *      // only this test will be executed
 *  }
 *
 *  ...
 * }
 * </code></pre>
 */
class SingleTestRule implements TestRule { }


Modified text is an extract of the original Stack Overflow Documentation
के तहत लाइसेंस प्राप्त है CC BY-SA 3.0
से संबद्ध नहीं है Stack Overflow