¿Existe una etiqueta javadoc para documentar parámetros de tipo genérico?

165

He estado revisando la documentación de javadoc en el sitio de Sun, tratando de encontrar si hay una etiqueta javadoc que pueda usarse para documentar la firma de tipo genérico de una clase o método.

Algo parecido @typeparam, similar a lo habitual @param, pero aplicable tanto a los tipos como a los métodos, p. Ej.

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

Sospecho que no existe tal etiqueta: no puedo encontrar ninguna mención de ella en ningún lado, y los documentos de la API JavaSE no muestran ningún signo de ello, pero parece una omisión extraña. ¿Alguien puede arreglarme?

skaffman
fuente
77
¿Escribir los javadocs adecuados?
Timo Willemsen
2
Tenga en cuenta que para la mayoría de las clases realmente no hay nada interesante que decir sobre el parámetro de tipo, porque el parámetro de tipo se define esencialmente por cómo aparece en los métodos del objeto. Me saltaría la @param <T>mayor parte del tiempo y solo lo uso cuando realmente no está claro.
Kevin Bourrillion
3
Veo lo que está diciendo, pero por esa razón, lo mismo se aplica al uso de los @paramparámetros del método. Los estándares de codificación de Sun dicen explícitamente que @paramdebe usarse incluso si el significado del parámetro del método es claro.
skaffman
3
Además de eso. La buena programación de API debe ser lo más autodocumentable posible ¿Eso significa que una API no necesita documentación? No.
Timo Willemsen
La documentación de @param proporciona instrucciones para los parámetros de tipo. Eso sí, Oracle podría hacer un mejor trabajo publicitando este documento.
Michael Allan

Respuestas:

235

Debería hacerse así:

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

}

Fuente

Timo Willemsen
fuente
66
Doh ... OK, eso es vergonzosamente obvio ... sin embargo, plantea la pregunta de por qué las clases JavaSE (por ejemplo Collection) no lo usan.
skaffman
66
LinkedList lo usa: java.sun.com/j2se/1.5.0/docs/api/java/util/LinkedList.html
Timo Willemsen
9
@skaffman Un poco tarde, por supuesto, pero plantea la pregunta, no la plantea .
Thor84no
66
@ Thor84no Desde su enlace: Algunas autoridades consideran que el uso de "plantea la pregunta" como una forma de decir "plantea la pregunta" o "evade la pregunta" ya no es un error porque ha alcanzado un uso tan amplio.
Matt R
8
Es una pena que IntelliJ complete como HTML en este caso.
Snicolas
27

Si. Simplemente use la etiqueta @param e incluya corchetes angulares alrededor del parámetro de tipo.

Me gusta esto:

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