重载方法的 Javadoc 重用 [英] Javadoc reuse for 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屋！
