重载方法的 Javadoc 重用

我正在开发一个包含许多同名方法的 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 扩展吗？或者有一个很好的理由，为什么这不支持，我错过了？

20865 次浏览
小开
最佳答案

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)
*/
小开

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.

/**
* 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 );
小开

There is likely no good standard method, since even the JDK9 source code simply copy pastes large chunks of documentation around, e.g., at:

4 lines of comment are repeated. Yikes, non-DRYness.

小开

Put the documentation to the interface, if you can. Classes that implement the interface will then inherit the 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}:

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

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:

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:

https://brixomatic.wordpress.com/2010/03/10/dealing-with-immutability-and-long-constructors-in-a-fluent-way/

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.


提交答案