Javadoc重用和重载方法

I'm developing an API with many identically named methods that just differ by signature, which I guess is fairly common. They all do the same thing, except that they initialize various values by defaults if the user does not want to specify. As a digestible example, consider

我正在开发一个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);
}

The essential action performed by all of these methods is the same; a tree is planted in the forest. Many important things users of my API need to know about adding trees hold for all these methods.

所有这些方法执行的基本操作是相同的;森林里种了一棵树。对于所有这些方法，我的API的用户需要了解关于添加树的许多重要内容。

Ideally, I would like to write one Javadoc block that is used by all methods:

理想情况下，我希望编写一个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%.
   */

In my imagination, a tool could magically choose which of the @params apply to each of the methods, and thus generate good docs for all methods at once.

在我的想象中，一个工具可以神奇地选择对每个方法应用的@params中的哪一个，从而同时为所有方法生成好的文档。

With Javadoc, if I understand it correctly, all I can do is essentially copy&paste the same javadoc block five times, with only a slightly differing parameter list for each method. This sounds cumbersome to me, and is also difficult to maintain.

对于Javadoc，如果我正确地理解了它，我所能做的就是将相同的Javadoc块复制5次，每个方法的参数列表略有不同。这听起来很麻烦，也很难维护。

Is there any way around that? Some extension to javadoc that has this kind of support? Or is there a good reason why this is not supported that I missed?

有办法解决这个问题吗?对javadoc的一些扩展有这种支持吗?或者有一个很好的理由为什么我没有支持它?

4 个解决方案

#1

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.

我不知道是否有任何支持，但是，我将用大多数参数完全javadoc方法，然后在其他javadoc中引用它。我认为它足够清晰，避免冗余。

/**
 * {@code fruitType} defaults to {@link FruitType#Banana}.
 *
 * @see Forest#addTree(int, Fruit, int)
 */

#2

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.

我将只记录您的“最完整”方法(在本例中为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 );

#3

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

很可能没有很好的标准方法，因为即使是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 l417
http://hg.openjdk.java.net/jdk9/jdk9/jdk/file/07175dc5b2da/src/java.desktop/share/classes/java/awt/Container.java#l464
http://hg.openjdk.java.net/jdk9/jdk9/jdk/file/07175dc5b2da/src/java.desktop/share/classes/java/awt/Container.java l464

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

4行评论被重复。哎,non-DRYness。

#4

Put the documentation to the interface, if you can. Classes that implement the interface will then inherit the javadoc.

如果可以，将文档放到接口中。实现接口的类随后将继承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}:

如果您想继承文档并向其添加自己的内容，可以使用{@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

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:

正如我所理解的，这并不是您想要的(您希望避免在同一个类/接口中的方法之间重复)。为此，您可以使用其他人描述的@see或@link，或者考虑您的设计。也许您希望避免重载方法，而是使用带有参数对象的单个方法，如下所示:

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:

你可能想看看这个复制-mutator模式:

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.

根据参数组合的数量，这可能是一种更简单、更简洁的方式，因为params类可以捕获默认值，并为每个参数设置一个javadoc。

#1