गुणों का जावेदोक कैसे लिखें?

Question 1

मैं अक्सर अपने आप को एक दुविधा के साथ पाता हूँ जब गुणों के लिए javadoc लिखते हैं / एक "सरल" POJO वर्ग के सदस्यों के लिए केवल गुण और गेटर्स और सेटर (DTO-style) पकड़े होते हैं ...।

1) संपत्ति के लिए javadoc लिखें
या ...
2) पाने वाले के लिए javadoc लिखें

यदि मैं संपत्ति के लिए javadoc लिखता हूं, तो मेरी IDE (ग्रहण) (स्वाभाविक रूप से) यह प्रदर्शित करने में सक्षम नहीं होगी जब मैं बाद में कोड पूरा होने के माध्यम से पीओजेओ तक पहुंचता हूं। और कोई मानक javadoc टैग नहीं है जो मुझे getter-javadoc को वास्तविक संपत्ति javadoc से लिंक करने देता है।

एक उदाहरण:

public class SomeDomainClass {

  /**
   * The name of bla bla bla
   */
  private String name;

  /**
   * @return INSERT SOME SMART JAVADOC TAG LINKING TO name's javadoc
   */
  public String getName() {  
    return name;  
  }

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

अब तक मैं केवल प्रैक्टिस करने के लिए अपना विचार बना रहा हूं, न कि केवल प्रापकों को प्रलेखित करने के लिए। लेकिन यह सबसे अच्छा समाधान की तरह प्रतीत नहीं होता है ...

Question 2

जावदोक्स (-पिरिटिव) का उपयोग करते हुए आप निजी सदस्यों को शामिल कर सकते हैं और फिर उस फ़ील्ड प्रॉपर्टी से लिंक करने के लिए @link का उपयोग कर सकते हैं।

public class SomeDomainClass {
    /**
     * The name of bla bla bla
     */
    private String name;

    /**
     * {@link SomeDomainClass#name}
     */
    public String getName() {
        return name;
    }
}

वैकल्पिक रूप से, यदि आप सभी निजी सदस्यों के लिए Javadoc उत्पन्न नहीं करना चाहते हैं, तो आप सभी गेटर्स को दस्तावेज़ित करने और बसने वालों पर @link का उपयोग करने के लिए एक सम्मेलन कर सकते हैं।

public class SomeDomainClass {
    private String name;

    /**
     * The name of bla bla bla
     */
    public String getName() {
        return name;
    }

    /**
     * {@link SomeDomainClass#getName}
     */
    public void setName(String name) {
        this.name = name;
    }
}

Question 3

लोम्बोक ऐसे कार्यों के लिए बहुत सुविधाजनक पुस्तकालय है।

@Getter
@Setter
public class Example {
    /**
     * The account identifier (i.e. phone number, user name or email) to be identified for the account you're
     * requesting the name for
     */
    private String name;
}

आप सभी की जरूरत है! @Getterएनोटेशन प्रत्येक निजी क्षेत्र के लिए एक गेटर विधि बनाकर उसे जावाडोक देते हैं।

पुनश्च : पुस्तकालय में कई शांत विशेषताएं हैं जिन्हें आप जांचना चाहते हैं

Question 4

मैं ग्रहण के स्वत: पूर्ण होने के बाद दोनों को सहायता करता हूं।

सबसे पहले, मैं संपत्ति का दस्तावेज:

/**
 * The {@link String} instance representing something.
 */
private String someString;

फिर, मैं इसे पाने वाले को कॉपी और पेस्ट करता हूं:

/**
 * The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

ग्रहण के साथ, @ ग्रेट के बयानों में एक स्वत: पूर्णता होती है - इसलिए, मैं शब्द को जोड़ देता हूं, "t" को कम कर देता है, और वाक्य को "t" के साथ कॉपी करता है। मैं तब @return (ग्रहण स्वत: पूर्ण के साथ) का उपयोग करता हूं, वाक्य पेस्ट करता हूं, और फिर वापसी में टी को ऊपर ले जाता हूं। यह तो इस तरह दिखता है:

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

अंत में, मैं उस दस्तावेज़ को सेटर में कॉपी करता हूँ:

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

फिर, मैं इसे संशोधित करता हूं और ग्रहण के स्वत: पूर्ण होने पर आप न केवल @param टैग बल्कि पैरामीटर का नाम भी प्राप्त कर सकते हैं:

/**
 * Sets the {@link String} instance representing something.
 * @param someString The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

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

ध्यान दें कि वाक्य हमेशा T से शुरू नहीं हो सकता है - यह केवल पहला अक्षर है जिसे चिपकाने में अनपेक्षित / पुनर्पूंजीकृत किया जाना है।

Question 5

मुझे वास्तव में लगता है कि यह एक समस्या है और आधिकारिक जवादोक गाइड इसके बारे में कुछ नहीं बताता है। C # गुणों के उपयोग के साथ एक सुरुचिपूर्ण तरीके से इसे हल कर सकता है (मैं C # में कोड नहीं करता, लेकिन मुझे वास्तव में लगता है कि यह एक अच्छी सुविधा है)।

लेकिन मेरे पास एक अनुमान है: यदि आपको यह समझाने की आवश्यकता है कि कुछ स्ट्रिंग क्या है, तो शायद यह आपके कोड के बारे में `` बुरा छोटा '' है। इसका मतलब यह हो सकता है कि आपको SomeString टाइप करने के लिए SomeClass लिखना चाहिए, इसलिए आप बताएंगे कि SomeClring प्रलेखन में कुछString क्या है, और बस गेटवे / सेटर में javadocs आवश्यक नहीं होगी।