java Javadoc 重用和重载方法
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/2558695/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Javadoc reuse for and overloaded methods
提问by skrebbel
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
我正在开发一个 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);
}
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.
所有这些方法执行的基本操作是相同的；森林里种了一棵树。我的 API 的用户需要了解有关为所有这些方法添加树的许多重要事项。
Ideally, I would like to write one Javadoc block that is used by all methods:
理想情况下，我想编写一个所有方法都使用的 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%.
*/
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.
在我的想象中，一个工具可以神奇地选择哪些@params 应用于每个方法，从而一次为所有方法生成好的文档。
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，如果我理解正确的话，我所能做的基本上就是将相同的 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 的一些扩展？或者是否有充分的理由不支持我错过的？
采纳答案by Sean Owen
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.
我不知道有任何支持，但是，我会完全 javadoc 具有最多参数的方法，然后像这样在其他 javadoc 中引用它。我认为它足够清楚，并且避免了冗余。
/**
* {@code fruitType} defaults to {@link FruitType#Banana}.
*
* @see Forest#addTree(int, Fruit, int)
*/
回答by Sled
I would just document your "fullest" method (in this case addTree(int,Fruit,int)) and then in the JavaDoc for other methods refer to this one and explain how/which defaults values are used for the arguments not provided.
我只会记录您的“最完整”方法（在这种情况下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 );
回答by Brixomatic
Put the documentation to the interface, if you can. Classes that implement the interface will then inherit the javadoc.
如果可以的话，把文档放到界面上。实现该接口的类将继承 javadoc。
interface X(){
/** does fooish things */
void foo();
}
class Ax implements X{ //automatically inherits the Javadoc of "X"
@Override
public void foo(){/*...*/}
}
In case you want to inherit the documentation and add your own stuff to it, you can use {@inheritDoc}:
如果您想继承文档并向其中添加自己的内容，可以使用 {@inheritDoc}：
class Bx implements X{
/**
* {@inheritDoc}
* May fail with a RuntimeException, if the machine is too foo to be true.
*/
@Override
public void foo(){/*...*/}
}
See also: http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#inheritingcomments
另见：http: //docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#inheritingcomments
Now as I understood, this is not exactly what you want (you want to avoid repetitions among the methods in the same class/interface). For this you can use @see or @link, as described by others, or you might think about your design. Maybe you'd like to avoid overloading the method and use a single method with a parameter object instead, like so:
现在据我所知，这不是你想要的（你想避免在同一个类/接口中的方法之间重复）。为此，您可以使用@see 或@link，如其他人所述，或者您可能会考虑您的设计。也许您想避免重载该方法，而是使用带有参数对象的单个方法，如下所示：
public Tree addTree(TreeParams p);
To be used like this:
像这样使用：
forest.addTree(new TreeParams().with(Fruits.APPLE).withLeaves(1500).withHeight(5));
You might like to have a look at this copy-mutator pattern here:
您可能想在此处查看此 copy-mutator 模式：
Depending on the amount of parameter combinations this could be the easier and cleaner way, since the Params-Class could capture the defaults and have a javadoc for each parameter.
根据参数组合的数量，这可能是更简单、更简洁的方法，因为 Params-Class 可以捕获默认值并为每个参数提供一个 javadoc。
