Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Javadoc reuse for overloaded methods

Tags:

java

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

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?

like image 285
skrebbel Avatar asked Apr 01 '10 07:04

skrebbel


People also ask

Can methods be overloaded multiple times?

Introduction. Method overloading is a salient feature in Object-Oriented Programming (OOP). It lets you declare the same method multiple times with different argument lists.

What does @SEE mean in Javadoc?

We can use the @see and @link tag multiple times in a class, package, or method. The @see tag declares references that point to an external link, class, or method. The @link tag can also be used multiple times for declaring inline links or in contrast with other block tags.

How do you reference another method in Javadoc?

Javadoc provides the @link inline tag for referencing the members in the Java classes. We can think of the @link tag as similar to the anchor tag in HTML, which is used to link one page to another via hyperlinks. Similar to the anchor tag, the path_to_member is the destination, and the label is the display text.

Is Javadoc still used?

Javadoc is pretty much the accepted standard for documenting java code.


2 Answers

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)  */ 
like image 171
Sean Owen Avatar answered Sep 20 '22 07:09

Sean Owen


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 ); 
like image 28
Sled Avatar answered Sep 21 '22 07:09

Sled