重载方法的 Javadoc 重用答案

【问题标题】：Javadoc reuse for overloaded methods重载方法的 Javadoc 重用
【发布时间】：2011-02-03 06:15:52
【问题描述】：

我正在开发一个 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 的一些扩展？还是有充分的理由不支持我错过的？

【问题讨论】：

很好的问题和很好的描述，谢谢。

标签： java javadoc

【解决方案1】：

我不知道有什么支持，但是，我会完全用 javadoc 包含最多参数的方法，然后像这样在其他 javadoc 中引用它。我认为它足够清楚，并且避免了冗余。

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

【讨论】：

奇怪，当我从不同的文件中引用该方法时，这有效，但不是从同一个文件中（在 Mac 上的 Eclipse 4.7 中）——当你试图弃用一个重载时，这很痛苦并将调用者指向未弃用的重载。
@Sridhar-Sarnobat：在同一个文件中，它应该只是@see #addTree(int, Fruit, int)（没有Forest）
Eclipse 不允许我单击该方法以将我带到引用的方法:(

【解决方案2】：

我只想记录您的“最完整”方法（在本例中为 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 );

【讨论】：

不幸的是，当你有一个不同类型的参数时，它有点分崩离析。

【解决方案3】：

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

4 行注释重复。哎呀，不干燥。

【讨论】：

【解决方案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));

您可能想在此处查看此复制修改器模式：

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

根据参数组合的数量，这可能是更简单、更简洁的方法，因为 Params-Class 可以捕获默认值并为每个参数提供一个 javadoc。

【讨论】：