[英]Javadoc reuse for overloaded methods
我正在开发一个 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 的一些扩展? 或者我错过了为什么不支持这个的充分理由?
我不知道有任何支持,但是,我会完全 javadoc 具有最多参数的方法,然后像这样在其他 javadoc 中引用它。 我认为它足够清楚,并且避免了冗余。
/**
* {@code fruitType} defaults to {@link FruitType#Banana}.
*
* @see Forest#addTree(int, Fruit, int)
*/
我只会记录您的“最完整”方法(在本例中为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 );
可能没有好的标准方法,因为即使是 JDK9 源代码也只是简单地复制粘贴大量文档,例如,在:
4 行注释重复。 哎呀,非干燥。
如果可以的话,把文档放到界面上。 实现该接口的类将继承 javadoc。
interface X(){
/** does fooish things */
void foo();
}
class Ax implements X{ //automatically inherits the Javadoc of "X"
@Override
public void foo(){/*...*/}
}
如果您想继承文档并向其中添加自己的内容,可以使用 {@inheritDoc}:
class Bx implements X{
/**
* {@inheritDoc}
* May fail with a RuntimeException, if the machine is too foo to be true.
*/
@Override
public void foo(){/*...*/}
}
另见: http : //docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#inheritingcomments
现在据我所知,这不是你想要的(你想避免在同一个类/接口中的方法之间重复)。 为此,您可以使用@see 或@link,如其他人所述,或者您可能会考虑您的设计。 也许您想避免重载该方法,而是使用带有参数对象的单个方法,如下所示:
public Tree addTree(TreeParams p);
像这样使用:
forest.addTree(new TreeParams().with(Fruits.APPLE).withLeaves(1500).withHeight(5));
您可能想在此处查看此 copy-mutator 模式:
根据参数组合的数量,这可能是更简单、更简洁的方法,因为 Params-Class 可以捕获默认值并为每个参数提供一个 javadoc。
声明:本站的技术帖子网页,遵循CC BY-SA 4.0协议,如果您需要转载,请注明本站网址或者原文地址。任何问题请咨询:yoyou2525@163.com.