How to Efficiently Document Overloaded Methods in Javadoc?

How can I efficiently document overloaded methods in Javadoc without duplicating the same Javadoc block for each one?

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);
}

In Java, Javadoc does not natively support reusing comments for overloaded methods directly. However, there are strategies to document overloaded methods effectively without redundancy. This guide will explore the common approaches for maintaining clarity and improving documentation practices in your API.

/**  
 * Plants a new tree in the forest. Please note that it may take  
 * up to 30 years for the tree to be fully grown.  
 *  
 * <p>  
 * The following details pertain to the method variants:  
 * <ul>  
 *   <li><code>addTree()</code>: Adds a tree with default values.</li>  
 *   <li><code>addTree(int amountOfLeaves)</code>: Sets specific leaves.</li>  
 *   <li><code>addTree(int amountOfLeaves, Fruit fruitType)</code>: Defines fruit type.</li>  
 *   <li><code>addTree(int amountOfLeaves, int height)</code>: Sets height.</li>  
 *   <li><code>addTree(int amountOfLeaves, Fruit fruitType, int height)</code>: All parameters.</li>  
 * </ul>  
 * <p>  
 * @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 height in centimeters. Actual height may differ  
 * by up to 15%.  
 */
public Tree addTree(int amountOfLeaves, Fruit fruitType, int height) { /* implementation */ }

Causes

• Javadoc requires separate documentation blocks for each method even if they share similar functionality, leading to code duplication.
• The lack of built-in support for parameter-specific documentation across overloaded methods results in maintainability issues.
• Most developers copy and paste the same doc block with slight modifications, which can introduce errors or inconsistencies during updates.

Solutions

• Utilize Java's `@inheritDoc` tag to inherit documentation. This tag allows you to inherit comments from a superclass or an interface, but it's generally more suited for implementations rather than overloads.
• Create a custom utility method or an external documentation generator to consolidate common documentation. This way, you can generate documentation from a single source.
• Consider placing detailed documentation or examples in the interface/class level comments instead of in individual method comments, which can give users a broader understanding.

Mistake: Not using the @inheritDoc tag, which could inherit documentation from a superclass/interface.

Solution: Implement the @inheritDoc in method declarations when applicable to reduce redundancy.

Mistake: Failing to update all overloaded method comments when changes are made to shared documentation.

Solution: Keep documentation in a central place, like using external tools or notes, to ensure consistency across all methods.

Mistake: Duplicating method documentation without any real difference in context, leading to cluttered API documentation.

Solution: Consider summarizing common functionality at the class level instead.