オーバーロードされたメソッドに対するJavadocの再利用

私は、署名だけが異なる同じ名前のメソッドを多数使用してAPIを開発していますが、これはかなり一般的だと思います。ユーザーが指定したくない場合にデフォルトでさまざまな値を初期化することを除いて、これらはすべて同じことを行います。消化しやすい例として、

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

これらすべての方法で実行される基本的なアクションは同じです。森の中に木が植えられています。私のAPIのユーザーがツリーの追加について知っておく必要のある多くの重要なことは、これらすべてのメソッドに当てはまります。

理想的には、すべてのメソッドで使用される1つの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ブロックを5回コピーして貼り付けるだけで、メソッドごとにパラメータリストがわずかに異なります。これは私には面倒に聞こえますが、保守も困難です。

それを回避する方法はありますか？この種のサポートがあるjavadocの拡張機能はありますか？それとも、私が見逃したのにこれがサポートされていない正当な理由がありますか？

サポートについてはわかりませんが、ほとんどの引数を使用してメソッドを完全にjavadocし、そのように他のjavadocで参照します。十分に明確で、冗長性を回避していると思います。

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

「最も完全な」メソッド（この場合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 );

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行のコメントが繰り返されます。Yikes、非乾燥。

可能であれば、ドキュメントをインターフェイスに配置します。インターフェイスを実装するクラスは、javadocを継承します。

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/

パラメータの組み合わせの量によっては、Params-Classがデフォルトをキャプチャし、各パラメータにjavadocを設定できるため、これはより簡単でクリーンな方法になる可能性があります。