Existe-t-il une balise javadoc pour documenter les paramètres de type générique?

165

J'ai parcouru la documentation javadoc sur le site de Sun, essayant de trouver s'il existe une balise javadoc qui peut être utilisée pour documenter la signature de type générique d'une classe ou d'une méthode.

Quelque chose comme @typeparam, similaire à l'habituel @param, mais applicable aux types ainsi qu'aux méthodes, par exemple

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

Je soupçonne qu'il n'y a pas de telle balise - je ne peux en trouver aucune mention, et la documentation de l'API JavaSE n'en montre aucun signe, mais cela semble être une étrange omission. Quelqu'un peut-il me redresser?

skaffman
la source
7
Pour écrire des javadocs appropriés?
Timo Willemsen le
2
Sachez que pour la plupart des classes, il n'y a vraiment rien d'intéressant à dire sur le paramètre de type, car le paramètre de type est essentiellement défini par la façon dont il apparaît dans les méthodes de l'objet. Je sautais la @param <T>plupart du temps et ne l'utilisais que lorsque ce n'était vraiment pas clair.
Kevin Bourrillion
3
Je vois ce que vous dites, mais selon cette logique, il en va de même pour l'utilisation des @paramparamètres de méthode. Les normes de codage de Sun indiquent explicitement que cela @paramdevrait être utilisé même si la signification du paramètre de méthode est claire.
skaffman
3
En plus de ça. Une bonne programmation API doit être aussi auto-documentée que possible. Cela signifie-t-il qu'une API n'a pas besoin de documentation? non.
Timo Willemsen
La documentation de @param donne des instructions pour les paramètres de type. Remarquez qu'Oracle pourrait mieux faire la publicité de ce document.
Michael Allan

Réponses:

235

Cela devrait être fait comme ceci:

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

}

La source

Timo Willemsen
la source
6
Doh ... OK, c'est d'une évidence embarrassante ... cela pose la question de savoir pourquoi les classes JavaSE (par exemple Collection) ne l'utilisent pas, cependant.
skaffman
6
LinkedList l'utilise: java.sun.com/j2se/1.5.0/docs/api/java/util/LinkedList.html
Timo Willemsen
9
@skaffman Un peu tard bien sûr, mais ça pose la question, ça ne pose pas la question .
Thor84no
6
@ Thor84no De votre lien: Certaines autorités considèrent que l'utilisation de «pose la question» comme une façon de dire «soulève la question» ou «élude la question» n'est plus une erreur car elle a atteint un tel usage.
Matt R
8
C'est dommage qu'IntelliJ se termine comme HTML dans ce cas.
Snicolas
27

Oui. Utilisez simplement la balise @param et incluez des crochets angulaires autour du paramètre de type.

Comme ça:

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