javadoc and overloaded methods

Question

Hi all,

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</code> 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 myPow(double,double) except the exponent is always 
 * presumed to be 2. 
 *
 * @see #myPow(double,double)
 */
 static double myPow( double base );