有没有适用于记录泛型类型参数的Javadoc标签？

Question

我一直在查看Sun网站上的javadoc文档，试图找到一个可以用来记录类或方法的泛型类型签名的javadoc标签。

类似于通常的@param，但适用于类型和方法，例如@typeparam。

/**
 *  @typeparam T This describes my type parameter
 */
class MyClass<T> {
}

我怀疑没有这样的标签 - 我无法在任何地方找到它的提及，而且JavaSE API文档中也没有显示出任何迹象，但这似乎是一个奇怪的遗漏。有人可以纠正我吗？

- skaffman

---

如何编写适当的Javadocs？ - Timo Willemsen

请注意，对于大多数类而言，关于类型参数并没有什么有趣的东西可说，因为类型参数基本上是由对象方法中出现的方式定义的。我会大部分时间跳过@param <T>，只有在确实不清楚时才使用它。 - Kevin Bourrillion

我明白你的意思，但是按照这个逻辑，同样适用于使用@param来表示方法参数。Sun的编码标准明确规定即使方法参数的含义很清晰，也应该使用@param。 - skaffman

除此之外，良好的 API 编程应尽可能自我说明。这是否意味着 API 不需要文档？不是的。 - Timo Willemsen

@param 的文档提供了类型参数的说明。请注意，Oracle可以更好地宣传这个文档。 - Michael Allan

Answer 1

应该这样做：

/**
 * @param <T> This describes my type parameter
 */
class MyClass<T>{

}

Source

：

该链接指向Java 1.5 文档中的 @param 标签页面。

- Timo Willemsen

---

哦...好吧，这显然很明显...不过这确实引出了一个问题，为什么JavaSE类（例如Collection）没有使用它呢？ - skaffman

链表使用它：http://java.sun.com/j2se/1.5.0/docs/api/java/util/LinkedList.html - Timo Willemsen

当然，有点晚了，但“raises the question”意味着引发问题，而不是“beg the question”的意思（译者注：beg the question是一种逻辑谬误）。请参考链接了解详情。 - Vala

从你的链接中得知：一些权威人士认为使用“begs the question”来表示“引出问题”或“回避问题”已经不再是错误的，因为它已经被广泛使用。 - Matt R

很遗憾，IntelliJ在这种情况下像HTML一样补全。 - Snicolas

Answer 2

是的。只需使用@param标签，并在类型参数周围加上尖括号即可。

像这样：

/**
 *  @param <T> This describes my type parameter
 */

- Dave DiFranco