Question

我正在开发一个带有许多同名方法的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用户需要了解的有关添加树的许多重要信息都适用于所有这些方法。

理想情况下，我想编写一个由所有方法使用的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块五次，每个方法只有一个稍微不同的参数列表。这听起来很麻烦，也很难维护。

有什么方法吗？对javadoc有一些扩展，有这种支持吗？或者有没有一个很好的理由为什么我不想支持这个？

Answer 1

我不知道有任何支持，但是，我会用大多数参数完全javadoc方法，然后在其他javadoc中引用它。我认为它足够清晰，并避免冗余。

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

Answer 2

我只记录你的“最完整”方法（在这种情况下为addTree(int,Fruit,int)），然后在JavaDoc中为其他方法引用这个方法并解释如何/哪些默认值用于未提供的参数。< / p>

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

可能没有好的标准方法，因为即使是JDK9源代码也只是复制粘贴大量文档，例如：

重复4行评论。哎呀，非干涸。

Answer 4

如果可以的话，将文档放到界面上。然后，实现该接口的类将继承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。

Javadoc重用和重载方法

4 个答案: