ओवरलोड विधियों के लिए जावदोक का पुन: उपयोग

Question 1

मैं कई नामांकित विधियों के साथ एक एपीआई विकसित कर रहा हूं जो केवल हस्ताक्षर से भिन्न है, जो मुझे लगता है कि काफी सामान्य है। वे सभी एक ही काम करते हैं, सिवाय इसके कि यदि उपयोगकर्ता निर्दिष्ट नहीं करना चाहते हैं, तो वे विभिन्न मानों को प्रारंभिक रूप से परिभाषित करते हैं। एक सुगम उदाहरण के रूप में, विचार करें

public interface Forest
{
  public Tree addTree();

  public Tree addTree(int amountOfLeaves);

  public Tree addTree(int amountOfLeaves, Fruit fruitType);

  public Tree addTree(int amountOfLeaves, int height);

  public Tree addTree(int amountOfLeaves, Fruit fruitType, int height);
}

इन सभी तरीकों से की जाने वाली आवश्यक क्रिया समान होती है; जंगल में एक पेड़ लगाया जाता है। मेरे एपीआई के कई महत्वपूर्ण चीजों को इन सभी तरीकों से पेड़ों की पकड़ को जोड़ने के बारे में जानने की जरूरत है।

आदर्श रूप में, मैं एक Javadoc ब्लॉक लिखना चाहूंगा जो सभी विधियों द्वारा उपयोग किया जाता है:

  /**
   * Plants a new tree in the forest. Please note that it may take
   * up to 30 years for the tree to be fully grown.
   *
   * @param amountOfLeaves desired amount of leaves. Actual amount of
   * leaves at maturity may differ by up to 10%.
   * @param fruitType the desired type of fruit to be grown. No warranties
   * are given with respect to flavour.
   * @param height desired hight in centimeters. Actual hight may differ by
   * up to 15%.
   */

मेरी कल्पना में, एक टूल जादुई तरीके से चुन सकता है कि कौन-से @params प्रत्येक विधि पर लागू होते हैं, और इस प्रकार एक ही बार में सभी विधियों के लिए अच्छे डॉक्स उत्पन्न करते हैं।

Javadoc के साथ, अगर मैं इसे सही ढंग से समझता हूं, तो मैं जो कर सकता हूं वह अनिवार्य रूप से एक ही javadoc ब्लॉक को पांच बार कॉपी और पेस्ट करना है, प्रत्येक विधि के लिए केवल थोड़ा अलग पैरामीटर सूची है। यह मेरे लिए बोझिल लगता है, और इसे बनाए रखना भी मुश्किल है।

क्या उसके आसपास कोई रास्ता है? इस तरह के समर्थन के लिए javadoc का कुछ विस्तार? या फिर एक अच्छा कारण है कि यह समर्थित नहीं है कि मैं चूक गया?

Question 2

मैं किसी भी समर्थन के बारे में नहीं जानता, लेकिन, मैं पूरी तरह से सबसे अधिक तर्कों के साथ विधि javadoc करूंगा, और फिर इसे अन्य javadoc में इस तरह से संदर्भित करूंगा। मुझे लगता है कि यह पर्याप्त रूप से स्पष्ट है, और अतिरेक से बचा जाता है।

/**
 * {@code fruitType} defaults to {@link FruitType#Banana}.
 *
 * @see Forest#addTree(int, Fruit, int)
 */

Question 3

मैं सिर्फ आपकी "पूर्णतम" विधि (इस मामले में addTree(int,Fruit,int)) का दस्तावेजीकरण करूंगा और फिर अन्य तरीकों के लिए JavaDoc में इस एक को संदर्भित करता हूं और समझाता हूं कि प्रदान किए गए तर्कों के लिए कैसे / कौन से डिफ़ॉल्ट मानों का उपयोग किया जाता है।

/**
 * Works just like {@link ThisClass#myPow(double,double)} except the exponent is always 
 * presumed to be 2. 
 *
 * @see ThisClass#myPow(double,double)
 */
 static double myPow( double base );

Question 4

संभावना नहीं है कि कोई अच्छी मानक विधि है, क्योंकि JDK9 स्रोत कोड भी केवल दस्तावेज़ों के बड़े हिस्से को चिपका देता है, जैसे:

टिप्पणी की 4 पंक्तियों को दोहराया जाता है। Yikes, गैर- DRYness।

Question 5

यदि आप कर सकते हैं, तो प्रलेखन को इंटरफ़ेस पर रखें। इंटरफ़ेस को लागू करने वाली कक्षाएं तब जेवाडॉक को विरासत में मिलेंगी।

interface X(){
 /** does fooish things */
 void foo();
}

class Ax implements X{ //automatically inherits the Javadoc of "X"
 @Override 
 public void foo(){/*...*/} 
}

यदि आप दस्तावेज़ को विरासत में लाना चाहते हैं और उसमें अपना सामान जोड़ना चाहते हैं, तो आप {@inheritDoc} का उपयोग कर सकते हैं:

class Bx implements X{
 /**
  * {@inheritDoc}
  * May fail with a RuntimeException, if the machine is too foo to be true.
  */
 @Override 
 public void foo(){/*...*/}
}

इसे भी देखें: http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#inheritingcomments

अब जैसा कि मैंने समझा, यह ठीक वैसा नहीं है जैसा आप चाहते हैं (आप उसी वर्ग / इंटरफ़ेस के तरीकों के बीच दोहराव से बचना चाहते हैं)। इसके लिए आप दूसरों के द्वारा बताए गए @see या @link का उपयोग कर सकते हैं, या आप अपने डिजाइन के बारे में सोच सकते हैं। हो सकता है कि आप विधि को ओवरलोड करने से बचना चाहें और इसके बजाय किसी पैरामीटर ऑब्जेक्ट के साथ एकल विधि का उपयोग करें, जैसे:

public Tree addTree(TreeParams p);

इस तरह इस्तेमाल किया जाना है:

forest.addTree(new TreeParams().with(Fruits.APPLE).withLeaves(1500).withHeight(5));

आप इस प्रति-उत्परिवर्ती पैटर्न पर एक नज़र डालना पसंद कर सकते हैं:

https://brixomatic.wordpress.com/2010/03/10/dealing-with-immutability-and-long-constructors-in-a-fluent-way/

पैरामीटर संयोजनों की मात्रा के आधार पर यह आसान और साफ-सुथरा तरीका हो सकता है, क्योंकि परमेस-क्लास डिफॉल्टों को पकड़ सकता है और प्रत्येक पैरामीटर के लिए एक javadoc हो सकता है।