Reusing Javadoc for and overloaded methods

Question

I am developing an API with many identically named methods that differ only in signature, which I think is pretty common. All of them do the same, except that they initialize different default values ​​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 these methods is the same; tree planted in the forest. Many important things that my API users should know about adding trees for all of these methods.

Ideally, I would like to write a single 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, the tool could magically choose which of @params is applicable to each of the methods, and thus generate good documents for all methods at once.

With Javadoc, if I understand it correctly, all I can do is essentially copy and paste the same javadoc block five times, having only a slightly different list of parameters for each method. It sounds cumbersome to me, and it's also hard to maintain.

Is there any way? Some extension for javadoc that has such support? Or is there a good reason why this is not supported that I missed?

Answer 1

I don't know any support, but I would completely javadoc the method with most arguments, and then reference it in another javadoc like this. I think it is clear enough and avoids redundancy.

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

Answer 2

I would just document your "most complete" method (in this case addTree(int,Fruit,int) ), and then in JavaDoc for other methods, reference this and explain how / which default values ​​are used for 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 probably no good standard method, since even the JDK9 source code simply copies pastes of large pieces of documentation around, for example, 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 in the interface if you can. Classes that implement the interface then inherit javadoc.

 interface X(){ /** does fooish things */ void foo(); } class Ax implements X{ //automatically inherits the Javadoc of "X" @Override public void foo(){/*...*/} } 

If you want to inherit the documentation and add your own materials 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 that I understand, this is not quite 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 can think about your design. Perhaps you want to avoid method overloading and use one method with a parameter object, for example:

 public Tree addTree(TreeParams p); 

Used as follows:

 forest.addTree(new TreeParams().with(Fruits.APPLE).withLeaves(1500).withHeight(5)); 

You may like this copy-mutator template here:

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

Depending on the number of combinations of parameters, this can be a simpler and more understandable way, since Params-Class can capture default values ​​and have javadoc for each parameter.