it-swarm.com.de

Javadoc-Wiederverwendung für und überladene Methoden

Ich entwickle eine API mit vielen gleichnamigen Methoden, die sich nur durch die Signatur unterscheiden, was meiner Meinung nach ziemlich üblich ist. Sie alle tun dasselbe, außer dass sie verschiedene Werte standardmäßig initialisieren, wenn der Benutzer keine Angaben machen möchte. Als 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 allen diesen Methoden ausgeführt wird, ist dieselbe. Im Wald wird ein Baum gepflanzt. Viele wichtige Dinge, die Benutzer meiner API über das Hinzufügen von Bäumen für alle diese Methoden wissen müssen.

Im Idealfall möchte ich einen Javadoc-Block schreiben, der von allen Methoden verwendet wird:

  /**
   * 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 Vorstellung könnte ein Werkzeug auf magische Weise auswählen, welche der @ -Parameter auf jede der Methoden zutreffen, und so gute Dokumente für alle Methoden gleichzeitig erzeugen.

Wenn ich es richtig verstanden habe, kann ich mit Javadoc im Wesentlichen den gleichen Javadoc-Block fünfmal kopieren und einfügen, wobei sich für jede Methode nur eine etwas andere Parameterliste befindet. Das hört sich für mich umständlich an und ist auch schwer zu warten.

Gibt es einen Weg, um das zu umgehen? Eine Erweiterung von Javadoc, die diese Art von Unterstützung hat? Oder gibt es einen guten Grund, warum dies nicht unterstützt wird, was ich vermisst habe?

65
skrebbel

Ich kenne keine Unterstützung, aber ich würde die Methode mit den meisten Argumenten vollständig javadoc und dann wie in anderen javadoc darauf verweisen. Ich denke, es ist ausreichend klar und vermeidet Redundanzen.

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

Ich würde nur Ihre "fullest" -Methode (in diesem Fall addTree(int,Fruit,int)) dokumentieren und dann in JavaDoc für andere Methoden auf diese Methode verweisen und erklären, wie/welche Standardwerte für die nicht angegebenen Argumente verwendet werden.

/**
 * 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 );
8
ArtB

Es gibt wahrscheinlich keine gute Standardmethode, da selbst der JDK9-Quellcode einfach große Dokumentationsblöcke kopiert, z.

4 Zeilen Kommentar werden wiederholt. Yikes, keine Trockenheit.

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

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

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

Wenn Sie die Dokumentation erben und Ihre eigenen Elemente hinzufügen möchten, können Sie {@inheritDoc} verwenden:

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 es verstanden habe, ist dies nicht genau das, was Sie wollen (Sie möchten Wiederholungen zwischen den Methoden in derselben Klasse/Schnittstelle vermeiden). Sie können dazu @see oder @link verwenden, wie von anderen beschrieben, oder Sie denken über Ihr Design nach. Vielleicht möchten Sie die Methode nicht überlasten und stattdessen eine einzelne Methode mit einem Parameterobjekt verwenden, z.

public Tree addTree(TreeParams p);

So verwenden:

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

Sie können sich dieses Kopiermutator-Muster hier ansehen:

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

Je nach Anzahl der Parameterkombinationen kann dies die einfachere und sauberere Methode sein, da die Params-Klasse die Standardwerte erfassen und für jeden Parameter einen Javadoc haben kann.

0
Brixomatic