How to Document Generic Type Parameters in Javadoc

Last updated: December 5, 2023

Written by: baeldung

Reviewed by: Saajan Nagendra

Java

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

Distributed systems often come with complex challenges such as service-to-service communication, state management, asynchronous messaging, security, and more.

Dapr (Distributed Application Runtime) provides a set of APIs and building blocks to address these challenges, abstracting away infrastructure so we can focus on business logic.

In this tutorial, we'll focus on Dapr's pub/sub API for message brokering. Using its Spring Boot integration, we'll simplify the creation of a loosely coupled, portable, and easily testable pub/sub messaging system:

>> Flexible Pub/Sub Messaging With Spring Boot and Dapr

1. Overview

Generics in Java provide flexibility by allowing types to be parameters when defining a class, constructor, interface, or method. The @param tag is the standard tag to document generic type parameters when writing Java documentation.

In this tutorial, we’ll explore best practices for using the @param tag to document generic type parameters in Java.

2. @param Tag

The @param tag is the standard tag to document parameters and generic type parameters for public methods, constructors, classes, etc.

A good Javadoc comment must properly describe method parameters for easy comprehension. Here’s the basic basic syntax:

/**
 * @param [parameter name] [parameter description]
 */

The syntax starts with the @param tag and a placeholder for the parameter name in a method or constructor signature. Finally, we have a placeholder to describe the purpose of the parameter.

For generic type, there’s a slight change in the syntax:

/**
 * @param [<parameter type>] [parameter type description]
 */

The parameter type must be inside an angle bracket. Then, we describe the type parameter.

3. Using @param Tag With Generic Type

Let’s see an example code that uses @param with a generic type parameter:

/**
 * 
 * @param <T> The type of the first value in the pair.
 * @param <S> The type of the second value in the pair.
 */
class Pair<T, S> {
    public T first;
    public S second;
    Pair(T a, S b) {
        first = a;
        second = b;
    }
}

Here, we create a new generic class named Pair and define two types for the class. Next, we use the @param tag with the type parameter and then describe it.

Notably, the type parameter must be inside the angle bracket when documenting a generic class.

Here’s the generated Javadoc:

Moreover, let’s write Javadoc comments to describe the constructor parameters:

/**
 * Constructs a new Pair object with the specified values.
 *
 * @param a The first value.
 * @param b The second value.
 */
Pair(T a, S b) {
    first = a;
    second = b;
}

In the code above, we describe the constructor arguments using the @param tag. Unlike generic type parameters, the parameter name isn’t in angle brackets. This differentiates between type parameters and ordinary parameters when writing a Javadoc comment.

4. Possible Errors

There are chances for errors to occur while generating Javadoc for a generic type. First, forgetting to add the @param tag at the beginning of the Javadoc comment generates an unknown tag error:

/**
 * <T> The type of the first value in the pair.
 * @param <S> The type of the second value in the pair.
 */

The above Javadoc comment generates an error message due to the missing @param tag in the first statement:

error: unknown tag: T * <T> The type of the first value in the pair

Next, an error can occur when we introduce the same or another type of parameter inside the description:

/**
 * @param <T> The type of the first value in the Pair<T,S>.
 * @param <S> The type of the second value in the Pair<T,S>.
 */

Here, we specify the generic class name in the description. However, the Javadoc generator treats the tag in the description as an HTML tag. Also, it expects a closing tag.

Here’s the error message:

error: malformed HTML * @param <T> The type of the first value in the Pair<T,S>

Let’s solve this error by escaping the angle brackets:

/**
 * @param <T> The type of the first value in the Pair&lt;T,S&gt;.
 * @param <S> The type of the second value in the Pair&lt;T,S&gt;.
 */

Here, the angle brackets “<” and “>” are escaped as “&lt;” and “>” respectively to avoid HTML parse error.

Alternatively, we can solve this error by using the @code tag in our description:

/**
 * @param <T> The type of the first value in the {@code Pair<T,S>}.
 * @param <S> The type of the second value in the {@code Pair<T,S>}.
 */

Using the @code tag looks cleaner and well-suited for this use case.

5. Conclusion

In this article, we learned how to document generic type parameters using the @param tag. Additionally, we saw the possible errors we may encounter and how to solve them.

The code backing this article is available on GitHub. Once you're logged in as a Baeldung Pro Member, start learning and coding on the project.