Esiste un tag javadoc per documentare i parametri di tipo generico?

165

Ho esaminato la documentazione di javadoc sul sito di Sun, cercando di scoprire se esiste un tag javadoc che può essere utilizzato per documentare la firma di tipo generico di una classe o di un metodo.

Qualcosa di simile @typeparam, simile al solito @param, ma applicabile ai tipi e ai metodi, ad es

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

Ho il sospetto che non ci sia un tale tag - non riesco a trovare alcun riferimento da nessuna parte e i documenti dell'API JavaSE non ne mostrano alcun segno, ma sembra una strana omissione. Qualcuno può darmi ragione?

java javadoc

— skaffman
fonte

Per scrivere javadocs corretto?

— Timo Willemsen,

Tenere presente che per la maggior parte delle classi non c'è davvero nulla di interessante da dire sul parametro type, poiché il parametro type è essenzialmente definito da come appare nei metodi dell'oggetto. Salterei la @param <T>maggior parte del tempo e lo userei solo quando non è davvero chiaro.

— Kevin Bourrillion,

Vedo quello che stai dicendo, ma in base a tale logica, lo stesso vale per l'uso dei @paramparametri del metodo. Gli standard di codifica di Sun affermano esplicitamente che @paramdovrebbero essere utilizzati anche se il significato del parametro del metodo è chiaro.

— Skaffman,

In aggiunta a ciò. Una buona programmazione dell'API dovrebbe essere il più autocompattante possibile. Ciò significa che un API non ha bisogno di una documentazione? no.

— Timo Willemsen,

La documentazione di @param fornisce istruzioni per i parametri di tipo. Intendiamoci, Oracle potrebbe fare un lavoro migliore pubblicizzando questo documento.

— Michael Allan il

Risposte:

235

Dovrebbe essere fatto proprio così:

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

}

fonte

— Timo Willemsen
fonte

Doh ... OK, questo è imbarazzantemente ovvio ... fa sorgere la domanda sul perché le classi JavaSE (ad esempio Collection) non lo usano, però.

— Skaffman,

LinkedList lo utilizza: java.sun.com/j2se/1.5.0/docs/api/java/util/LinkedList.html

— Timo Willemsen

@skaffman Un po 'tardi ovviamente, ma solleva la domanda, non pone la domanda .

— Thor84no,

@ Thor84no Dal tuo link: alcune autorità considerano l'uso di "pone la domanda" come un modo di dire "solleva la domanda" o "elude la domanda" non si sbaglia più perché ha raggiunto un uso così ampio.

— Matt R,

È un peccato che IntelliJ completi come HTML in questo caso.

— Snicolas,

Sì. Basta usare il tag @param e includere parentesi angolari attorno al parametro type.

Come questo:

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

— Dave DiFranco
fonte