Javadoc 重用重载方法

java javadoc

2022-08-31 10:52: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的扩展有这种支持？还是有充分的理由为什么我错过了它不受支持？

答案 1

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

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

答案 2

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

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