Is there a javadoc tag for documenting generic type parameters?

java

generics

documentation

best-practices

byAnton Shumikhin·Jan 10, 2025

To document generics in Java, employ the @param <T> for each generic type parameter:

/**
 * Container of type T elements.
 *
 * @param <T> Type of the element
 */
public class Container<T> {
    
    private T element;

    /**
     * @param element to be kept safe, like your secret recipes
     */
    public void set(T element) {
        this.element = element;
    }

    /**
     * @return the well-guarded element
     */
    public T get() {
        return element;
    }
}

Emphasize <T> right after @param to explain the purpose of the generic in a nutshell.

Digging deeper into the `@param` usage

Java's @typeparam tag may not exist, but you can fluently illustrate generic type parameters using the @param tag. It's effectively a two-in-one solution: it annotates method and type parameters.

`@param` in the limelight

While penning down generics, clarity is paramount. Serve up the role of the generics on a silver platter with these top tips:

Furnish an unambiguous description outlining the context of the type parameter.
If the type parameter is bounded (e.g., <T extends Comparable<T>>), spill the beans on how the bounds influence its usage.
Don't hold back from giving illustrative examples. They can clarify the operation of the generic type within the API.

Navigating through potential edge cases

Masterfully documenting generics means being prepared for a few curveballs:

If a method introduces its own type parameters, make sure to document these separately from those of the class.
In cases of nested generics Map<K, V>, clarify each type parameter (<K> and <V>) independently.
Wildcards (?) in generics can be tricky. Detail the usage and limitations when they pop up.

Best practices for `@param`

For a touchdown, follow this playbook:

Mirror standards from "Effective Java" by Joshua Bloch when documenting generics.
Use the Oracle documentation as a springboard for appropriate @param usage.

Structuring class and method-level documentation

When dealing with complex class hierarchies, it is essential to ensure type parameters of the parent class are explained in the child class.

The practical side: Generics in action

Lastly, provide concrete examples of how the generic type will be utilized in real-world scenarios. Show object creation, method invocations, and potential outcomes when using generics.

explain-codes / Java / Is there a javadoc tag for documenting generic type parameters?

Linked

How do I get a class instance of generic type T?



How to use Class<T> in Java?



Java Generics With a Class & Interface - Together



Static method in a generic class?



Mockito: List Matchers with generics

