web-dev-qa-db-ja.com

メソッドのオーバーロードされた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への拡張？または、これがサポートされていないのに私が逃した正当な理由はありますか？

javajavadoc
76
skrebbel

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

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

私はあなたの「完全な」メソッド（この場合は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 );
10
Tobogganski

JDK9のソースコードでさえ、たとえば次の場所にあるドキュメントの大きなチャンクを単にコピーして貼り付けるだけなので、適切な標準的な方法はおそらくありません。

コメントは4行繰り返します。いや、非乾燥。

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

可能であれば、ドキュメントをインターフェイスに配置します。インターフェースを実装するクラスは、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));

このcopy-mutatorパターンをこちらで確認してください。

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

パラメータの組み合わせの量によっては、Params-Classがデフォルトをキャプチャして各パラメータのjavadocを取得できるため、これはより簡単でわかりやすい方法です。

0
Brixomatic