Javadoc重载方法的复用

18 浏览
0 Comments

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的用户需要了解关于添加树的许多重要事项都适用于所有这些方法。

理想情况下，我希望编写一个Javadoc块，所有方法都可以使用：

  /**
   * 在森林中种植一棵新树。请注意，树木完全成长可能需要多达30年的时间。
   *
   * @param amountOfLeaves 所需叶子数量。成熟时实际叶子数量可能有10%的差异。
   * @param fruitType 所需的果实类型。不保证口味。
   * @param height 所需的高度（以厘米为单位）。实际高度可能有15%的差异。
   */

根据我的想象，一个工具可以自动选择哪些@params适用于每个方法，并为所有方法生成良好的文档。

使用Javadoc，如果我理解正确，我只能将相同的javadoc块复制粘贴五次，每个方法只有稍微不同的参数列表。这对我来说听起来很麻烦，而且也很难维护。

有没有什么办法可以解决这个问题？有没有一些扩展Javadoc的方法来支持这种功能？或者有没有什么我错过的支持的好理由？

0