重载方法的 Javadoc 重用

Question

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

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.

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

  /**
   * 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.

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.

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?

Answer 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.

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

Answer 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.

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

Answer 3

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

• 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 lines of comment are repeated. Yikes, non-DRYness.

Answer 4

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.