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%. */
在我的想象中，一个工具可以神奇地select哪个@params适用于每种方法，从而为所有方法一次生成好的文档。
用Javadoc，如果我理解正确，我所能做的就是复制和粘贴相同的javadoc块五次，每个方法只有一个略有不同的参数列表。 这听起来很麻烦，也很难维护。
有没有什么办法呢？ javadoc有这种支持的一些扩展？ 还是有一个很好的理由，为什么不支持，我错过了？
我不知道有什么支持，但是，我会完全javadoc最有争议的方法，然后在其他javadoc像这样引用它。 我认为这足够清楚，避免冗余。
/** * {@code fruitType} defaults to {@link FruitType#Banana}. * * @see Forest#addTree(int, Fruit, int) */
我只是logging你的“最完整的”方法（在这种情况下， 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源代码只是简单地复制粘贴大量文档，例如：
- http://hg.openjdk.java.net/jdk9/jdk9/jdk/file/07175dc5b2da/src/java.desktop/share/classes/java/awt/Container.java#l417
- http://hg.openjdk.java.net/jdk9/jdk9/jdk/file/07175dc5b2da/src/java.desktop/share/classes/java/awt/Container.java#l464
重复4行评论。 哎呀，非DRYness。
把文档放到界面上，如果可以的话。 实现接口的类将inheritancejavadoc。
interface X(){ /** does fooish things */ void foo(); } class Ax implements X{ //automatically inherits the Javadoc of "X" @Override public void foo(){/*...*/} }
如果您想inheritance文档并添加自己的内容，则可以使用{@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（如其他人所述），也可以考虑您的devise。 也许你想避免重载方法，并使用一个方法与一个参数对象，而不是像这样：
public Tree addTree(TreeParams p);
要这样使用：
forest.addTree(new TreeParams().with(Fruits.APPLE).withLeaves(1500).withHeight(5));
你可能想在这里看看这个复制 – 增变模式：
根据参数组合的数量，这可能是更简单和更干净的方式，因为Params-Class可以捕获默认值，并为每个参数设置一个javadoc。
