How to Document Generic Type Parameters in Javadoc – 如何在 Javadoc 中记录通用类型参数

最后修改: 2023年 11月 6日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

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.

Java中的泛型允许在定义类、构造函数、接口或方法时将类型作为参数，从而提供了灵活性。@param 标记是编写 Java 文档时记录泛型类型参数的标准标记。

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

在本教程中，我们将探讨使用 @param 标记记录 Java 中通用类型参数的最佳实践。

2. @param Tag

2. @param 标记

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

@param 标记是记录公共方法、构造函数、类等的参数和通用类型参数的标准标记。

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

好的 Javadoc 注释必须正确描述方法参数，以便于理解。下面是基本的基本语法：

/**
 * @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.

语法以 @param 标记和方法或构造函数签名中参数名称的占位符开始。最后，我们还有一个占位符来描述参数的用途。

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

3.在通用类型中使用 @param 标记

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

让我们来看一个使用 @param 和通用类型参数的示例代码：

/**
 * 
 * @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.

在这里，我们创建了一个名为 Pair 的新泛类，并为该类定义了两种类型。接下来，我们使用 @param 标记来添加类型参数，然后对其进行描述。

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

值得注意的是，在记录泛型类时，类型参数必须位于角括号内。

Here’s the generated Javadoc:javadoc comment for generic type parameter

以下是生成的 Javadoc：javadoc comment for generic type parameter

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

此外，让我们编写 Javadoc 注释来描述构造函数参数：

/**
 * 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.

在上面的代码中，我们使用 @param 标记来描述构造函数参数。与通用类型参数不同的是，参数名称不在角括号内。这样在撰写 Javadoc 注释时，就可以区分类型参数和普通参数。

4. Possible Errors

4.可能出现的错误

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:

在生成泛型的 Javadoc 时，有可能会发生错误。首先，如果忘记在 Javadoc 注释的开头添加 @param 标记，就会产生未知标记错误：

/**
 * <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:

由于第一条语句中缺少 @param 标记，上述 Javadoc 注释生成了一条错误信息：

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.

在这里，我们在描述中指定了通用类名。但是，Javadoc 生成器会将描述中的标记视为 HTML 标记。此外，它还希望有一个结束标记。

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 “&gt;” respectively to avoid HTML parse error.

这里，角括号”<“和”>“分别转义为”&lt; “和”&gt;“，以避免 HTML 解析错误。

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

或者，我们可以在描述中使用 @code 标记来解决这个错误：

/**
 * @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.

使用 @code 标记看起来更简洁，非常适合这种使用情况。

5. Conclusion

5.结论

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.

在本文中，我们学习了如何使用 @param 标记记录通用类型参数。此外，我们还了解了可能遇到的错误及解决方法。

As always, the complete source code for the example is available over on GitHub.

一如既往，该示例的完整源代码可在 GitHub 上获取。