Javadoc für die Wiederverwendung und das überladen von Methoden

Entwickle ich eine API mit vielen gleichnamigen Methoden unterscheiden sich gerade durch die Signatur, die ich denke, ist ziemlich weit verbreitet. Sie alle tun das gleiche, außer dass Sie initialisieren Sie die verschiedenen Werte durch die Standardwerte, wenn der Benutzer nicht will, um anzugeben. Als verdaulich Beispiel

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

Wesentlichen Aktion, die von all diesen Methoden ist das gleiche; ein Baum ist gepflanzt in den Wald. Viele wichtige Dinge, die Nutzer meiner API wissen müssen über das hinzufügen von Bäumen halten für alle diese Methoden.

Im Idealfall würde ich mag zu schreiben, eine Javadoc-block, der von allen Methoden:

  /**
   * 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, ein tool könnte magisch die Wahl, welches der @params gelten für jede der Methoden, und erzeugen so gute docs für alle Methoden auf einmal.

Mit Javadoc, wenn ich es richtig verstehe, ist alles was ich tun kann, ist im wesentlichen copy&paste die gleichen javadoc-block fünf mal, mit nur leicht unterschiedlichen parameter-Liste für jede Methode. Das klingt umständlich, zu mir, und ist auch schwer aufrecht zu erhalten.

Gibt es eine Möglichkeit das umgehen? Einige Erweiterung zu javadoc, das diese Art von support? Oder gibt es einen guten Grund, warum dies nicht unterstützt, dass ich verpasst?

Gute Frage, und vorzüglich beschrieben, danke.

InformationsquelleAutor skrebbel | 2010-04-01

  1. 59

    Ich kenne keine Unterstützung, aber ich würde voll javadoc der Methode mit der die meisten Argumente, und dann finden Sie es in anderen javadoc-wie so. Ich denke, es ist hinreichend klar, und vermeidet Redundanz.

    /**
 * {@code fruitType} defaults to {@link FruitType#Banana}.
 *
 * @see Forest#addTree(int, Fruit, int)
 */
    Seltsam, das funktioniert, wenn ich mich auf die Methode aus einer anderen Datei, aber nicht in der gleichen Datei (in Eclipse 4.7 auf Mac) - und das ist ein Schmerz, wenn Sie versuchen, missbilligen eine überlastung und zeigen Sie Anrufer auf eine nicht-nicht überladen.
    Innerhalb der gleichen Datei sollte es einfach sein @see #addTree(int, Fruit, int) (Ohne Forest)
    Eclipse ist nicht erlaubt mir, klicken Sie auf die Methode an, mich auf die verwiesen wird 🙁

    InformationsquelleAutor Sean Owen

  2. 9

    Ich würde einfach dokumentieren Sie Ihre "vollste" - Methode (in diesem Fall addTree(int,Fruit,int) ) und dann in der JavaDoc für andere Methoden beziehen sich auf diese ein und erklären, wie/, die defaults Werte verwendet werden, für die Argumente nicht vorgesehen.

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

    InformationsquelleAutor ArtB

  3. 4

    Gibt es wahrscheinlich keine gute standard-Methode, da auch die JDK9-source-code einfach copy-Pasten große Teile der Dokumentation, z.B. bei:

    4 Zeilen des Kommentars wiederholt werden. Huch, nicht Trockenheit.

    InformationsquelleAutor Ciro Santilli 新疆改造中心996ICU六四事件

  4. 0

    Setzen Sie in der Dokumentation zu der Schnittstelle, wenn Sie können.
    Klassen, die das interface implementieren, wird dann Erben die javadoc.

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

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

    In Fall, dass Sie wollen, übernehmen die Dokumentation und fügen Sie Ihre eigenen Sachen, Sie nutzen kann {@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 habe, ist das nicht genau das, was Sie wollen (Sie wollen, um Wiederholungen zu vermeiden, unter die Methoden, die in der gleichen Klasse/interface). Für diese können Sie verwenden, @sehen, oder @link, wie beschrieben, von anderen, oder denken Sie vielleicht über Ihr design. Vielleicht möchten Sie vermeiden, überladen Sie die Methode, und verwenden Sie eine einzelne Methode mit einem parameter-Objekt statt, etwa so:

    public Tree addTree(TreeParams p);

    Werden wie folgt verwendet:

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

    Möchten Sie vielleicht einen Blick auf diese kopieren-mutator-Muster hier:

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

    Je nach der Menge der parameterkombinationen das könnte das einfacher und sauberer Weg, da die Params-Klasse konnte erfassen Sie die Standardeinstellungen, und haben eine javadoc für die einzelnen parameter.

    InformationsquelleAutor Brixomatic

Schreibe einen Kommentar