Javadoc重用和重载方法

内容来源于 Stack Overflow,并遵循CC BY-SA 3.0许可协议进行翻译与使用

  • 回答 (2)
  • 关注 (0)
  • 查看 (7)

我正在开发一个具有许多相同名称的方法的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有一些扩展,有这种支持?还是有一个很好的理由,为什么我错过了这个支持?

提问于
用户回答回答于

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

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

我只是记录你的“fullest”方法(在这种情况下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 );

扫码关注云+社区