1. 概述
Java中的泛型（/java-generics）通过在定义类、构造函数、接口或方法时允许类型成为参数，提供了灵活性。在编写Java文档时，@param 标签是标准的用于描述泛型类型参数的标签。
在这个教程中，我们将探讨使用@param 标签来在Java中文档化泛型类型参数的最佳实践。
2. @param 标签
@param 标签是用于文档化公共方法、构造函数、类等的参数和泛型类型参数的标准标签。
一个好的Javadoc注释必须恰当地描述方法参数，以便于理解。基本的语法如下：
/**
* @param [parameter name] [parameter description]
*/
语法以@param 标签开始，然后在方法或构造函数签名中提供参数名称的占位符，最后我们有占位符来描述参数的目的。
对于泛型类型，语法稍有不同：
/**
* @param [<parameter type>] [parameter type description]
*/
参数类型必须放在尖括号内，然后我们描述类型参数。
3. 使用@param 标签与泛型类型
让我们看一个使用@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;
}
}
这里，我们创建了一个名为Pair的新泛型类，并为类定义了两种类型。接下来，我们在@param 标签中使用类型参数并对其进行描述。
值得注意的是，在文档化泛型类时，类型参数必须位于尖括号内。
这是生成的Javadoc注释：
此外，让我们写一些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;
}
在上述代码中，我们使用@param 标签描述构造函数参数。与泛型类型参数不同，参数名称不放在尖括号中。这在编写Javadoc注释时区分了类型参数和普通参数。
4. 可能的错误
在生成包含泛型类型的Javadoc时，可能会出现错误。首先，如果在Javadoc注释的开头忘记添加@param 标签，会导致未知标签错误：
/**
* <T> The type of the first value in the pair.
* @param <S> The type of the second value in the pair.
*/
由于缺少注释中的@param 标签，上述Javadoc注释会产生错误消息：
error: unknown tag: T * <T> The type of the first value in the pair
其次，当我们在描述中引入相同或另一种类型的参数时，也可能出错：
/**
* @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>.
*/
在这里，我们在描述中指定了泛型类的名称。然而，Javadoc生成器将标签视为HTML标签，并期望一个关闭标签。
这是错误消息：
error: malformed HTML * @param <T> The type of the first value in the Pair<T,S>
让我们通过转义尖括号来解决这个问题：
/**
* @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>.
*/
这里，尖括号“*<”和“*>”分别被转义为“<”和“>”以避免HTML解析错误。
或者，我们可以使用@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>}.
*/
使用@code标签看起来更整洁，更适合这种情况。
5. 总结
在这篇文章中，我们学习了如何使用@param 标签来文档化泛型类型参数。此外，我们还了解了可能遇到的错误以及如何解决它们。
如往常一样，示例的完整源代码可在GitHub上找到：https://github.com/eugenp/tutorials/tree/master/core-java-modules/core-java-documentation。