Javadoc重用和重载方法 [英] Javadoc reuse for and overloaded methods

问题描述

我正在开发一个API，其中包含许多相同命名的方法，只是签名不同而已，这在我看来是很普遍的.它们都做相同的事情，不同之处在于，如果用户不想指定默认值，则它们会默认初始化各种值.作为一个易于理解的示例，请考虑

I'm developing an API with many identically named methods that just differ by signature, which I guess is fairly common. They all do the same thing, except that they initialize various values by defaults if the user does not want to specify. As a digestible example, consider

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用户需要了解许多重要事项，以了解如何为所有这些方法添加树.

The essential action performed by all of these methods is the same; a tree is planted in the forest. Many important things users of my API need to know about adding trees hold for all these methods.

理想情况下，我想编写一个可用于所有方法的Javadoc块:

Ideally, I would like to write one Javadoc block that is used by all methods:

  /**
   * 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应用于每个方法，从而一次为所有方法生成良好的文档.

In my imagination, a tool could magically choose which of the @params apply to each of the methods, and thus generate good docs for all methods at once.

使用Javadoc时，如果我正确理解的话，我所能做的就是将同一javadoc块复制并粘贴五次，每种方法的参数列表仅稍有不同.这对我来说听起来很麻烦，而且也很难维护.

With Javadoc, if I understand it correctly, all I can do is essentially copy&paste the same javadoc block five times, with only a slightly differing parameter list for each method. This sounds cumbersome to me, and is also difficult to maintain.

有什么办法解决吗?对javadoc的某种扩展具有这种支持?还是有一个很好的理由为什么我错过了不支持此功能?

Is there any way around that? Some extension to javadoc that has this kind of support? Or is there a good reason why this is not supported that I missed?

推荐答案

我不知道有什么支持，但是，我将使用参数最多的javadoc方法完全使用该方法，然后在其他javadoc中像这样引用它.我认为它已经足够清楚了，并且避免了重复.

I don't know of any support, but, I would fully javadoc the method with the most arguments, and then refer to it in other javadoc like so. I think it's sufficiently clear, and avoids redundancy.

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

这篇关于Javadoc重用和重载方法的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！