我正在开发一个带有许多同名方法的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有一些扩展,有这种支持吗？或者有没有一个很好的理由为什么我不支持这个？
Sea*_*wen 68
我不知道有任何支持,但是,我会用大多数参数完全javadoc方法,然后在其他javadoc中引用它.我认为它足够清晰,并避免冗余.
/**
* {@code fruitType} defaults to {@link FruitType#Banana}.
*
* @see Forest#addTree(int, Fruit, int)
*/
Sle*_*led 11
我只记录你的"最完整"方法(在这种情况下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 );