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<T,S>.
* @param <S> The type of the second value in the Pair<T,S>.
*/
Here, the angle brackets “<” and “>” are escaped as “<” 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.
As always, the complete source code for the example is available over on GitHub.
