我正在开发一个具有许多相同名称的方法的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有一些扩展,有这种支持?还是有一个很好的理由,为什么我错过了这个支持?
发布于 2018-03-27 12:58:35
我不知道有任何支持,但是,我会完全javadoc参数最多的方法,然后在其他javadoc中像这样引用它。我认为这足够清晰,并避免冗余。
/**
* {@code fruitType} defaults to {@link FruitType#Banana}.
*
* @see Forest#addTree(int, Fruit, int)
*/
发布于 2018-03-27 14:03:16
我只是记录你的“fullest”方法(在这种情况下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 );
https://stackoverflow.com/questions/-100003706
复制相似问题