Javadoc Wiederverwendung für und überladene Methoden

Question

Ich entwickle eine API mit vielen identisch benannten Methoden, die sich nur durch die Signatur unterscheiden, was ich denke, ziemlich häufig ist. Sie alle machen dasselbe, außer dass sie verschiedene Werte durch Standardwerte initialisieren, wenn der Benutzer dies nicht spezifizieren möchte. Als ein verdauliches Beispiel betrachten

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

Die wesentliche Aktion, die von all diesen Methoden durchgeführt wird, ist das gleiche; Ein Baum ist im Wald gepflanzt. Viele wichtige Dinge, die Benutzer meiner API über das Hinzufügen von Bäumen wissen müssen, gelten für alle diese Methoden.

Idealerweise möchte ich ein Javadoc Block schreiben, die von allen Methoden verwendet:

/** 
    * 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%. 
    */ 

In meiner Phantasie könnte ein Werkzeug auf magische Weise anwenden, welche der @params wählen, um jede der Methoden und Auf diese Weise können Sie gute Dokumente für alle Methoden gleichzeitig erstellen. Wenn ich es richtig verstehe, kann ich im Wesentlichen nur & kopieren den gleichen javadoc Block fünf Mal, mit nur einer leicht abweichenden Parameterliste für jede Methode. Das klingt für mich umständlich und ist auch schwer zu pflegen.

Gibt es einen Weg dahin? Eine Erweiterung von Javadoc, die diese Art von Unterstützung bietet? Oder gibt es einen guten Grund, warum das nicht unterstützt wird, was ich verpasst habe?

Answer 1

Ich kenne keine Unterstützung, aber ich würde die Methode mit den meisten Argumenten voll javadoc und dann in anderen Javadoc wie so verweisen. Ich denke, es ist ausreichend klar und vermeidet Redundanz.

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

Answer 2

Ich würde nur Ihre „vollen Zügen“ Methode (in diesem Fall addTree(int,Fruit,int)) und dann in der JavaDoc für andere Methoden dokumentieren diese verweisen und erklären, wie/die Standardwerte für die Argumente verwendet werden, nicht zur Verfügung gestellt.

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

Es ist wahrscheinlich keine gute Standardmethode, da selbst die JDK9 Quellcode einfach Pasten große Teile der Dokumentation zu kopieren um, zB bei:

• 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 Zeilen Kommentar werden wiederholt. Huch, Nicht-Trockenheit.

Answer 4

Legen Sie die Dokumentation zur Schnittstelle, wenn Sie können. Klassen, die die Schnittstelle implementieren, erben dann das Javadoc.

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

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

Falls Sie in der Dokumentation erben und Ihre eigenen Sachen, um es hinzuzufügen, können Sie {@inheritDoc}:

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

Siehe auch: http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#inheritingcomments

Nun, wie ich verstanden, dies ist nicht genau das, was Sie wollen (Sie wollen Wiederholungen zwischen den Methoden in der gleichen Klasse/Schnittstelle vermeiden). Dazu können Sie @see oder @link verwenden, wie von anderen beschrieben, oder Sie denken über Ihr Design nach.Vielleicht würden Sie die Methode zu vermeiden wie eine Überlastung und eine einzelne Methode mit einem Parameter-Objekt zu verwenden, statt, etwa so:

public Tree addTree(TreeParams p); 

Um wie folgt verwendet werden:

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

Vielleicht möchten Sie eine haben Blick auf diese Kopie-Mutator Muster hier:

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

Je nach Menge der Parameterkombinationen könnte dies den einfachen und sauberen Weg sein, da Die Params-Klasse könnte die Standardwerte erfassen und ein Javadoc für jeden Parameter haben.