जावाडोक पुन: उपयोग और अधिभारित विधियों

Question

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

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); 
} 

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

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

/** 
    * 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 की जो तरीकों में से प्रत्येक के लिए लागू है, और इस प्रकार सभी विधियों के लिए एक बार में अच्छे दस्तावेज़ उत्पन्न करते हैं।

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

क्या इसके आसपास कोई रास्ता है? जावडोक के लिए कुछ विस्तार जिसमें इस तरह का समर्थन है? या क्या कोई अच्छा कारण है कि यह समर्थित नहीं है कि मुझे याद आया?

Answer 1

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

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

Answer 2

मैं बस (इस मामले 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); 

Answer 3

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

• http://hg.openjdk.java.net/jdk9/jdk9/jdk/file/07175dc5b2da/src/java.desktop/share/classes/java/awt/Container.java#l417
• http://hg.openjdk.java.net/jdk9/jdk9/jdk/file/07175dc5b2da/src/java.desktop/share/classes/java/awt/Container.java#l464

टिप्पणी की 4 पंक्तियों को दोहराया जाता है। पसंद है, नॉन-ड्रवाईनेस।

Answer 4

यदि आप कर सकते हैं, तो दस्तावेज़ को इंटरफ़ेस पर रखें। इंटरफ़ेस को लागू करने वाले वर्ग तब जावाडोक का उत्तराधिकारी होंगे। {} @inheritDoc

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

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

मामले में आप प्रलेखन के वारिस और इसे करने के लिए अपने खुद के सामान जोड़ना चाहते हैं, तो आप उपयोग कर सकते हैं:

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)); 

आप एक है करने के लिए पसंद कर सकते हैं इस प्रति-mutator पैटर्न यहाँ देखें:

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

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