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?
77
¿Escribir los javadocs adecuados?
—
Timo Willemsen
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
—
Kevin Bourrillion
@param <T>
mayor parte del tiempo y solo lo uso cuando realmente no está claro.
Veo lo que está diciendo, pero por esa razón, lo mismo se aplica al uso de los
—
skaffman
@param
parámetros del método. Los estándares de codificación de Sun dicen explícitamente que @param
debe usarse incluso si el significado del parámetro del método es claro.
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