Gibt es ein Javadoc-Tag zum Dokumentieren generischer Typparameter?

165

Ich habe die Javadoc-Dokumentation auf der Sun-Website durchgesehen und versucht, herauszufinden, ob es ein Javadoc-Tag gibt, mit dem die generische Typensignatur einer Klasse oder Methode dokumentiert werden kann.

So etwas wie @typeparamdas Übliche @param, aber anwendbar auf Typen und Methoden, z

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

Ich vermute, dass es kein solches Tag gibt - ich kann es nirgendwo erwähnen, und die JavaSE-API-Dokumente zeigen keine Anzeichen dafür, aber es scheint eine seltsame Auslassung zu sein. Kann mich jemand in Ordnung bringen?

java javadoc

— Skaffman
quelle

Richtige Javadocs schreiben?

— Timo Willemsen

Beachten Sie, dass für die meisten Klassen wirklich nichts Interessantes über den Typparameter zu sagen ist, da der Typparameter im Wesentlichen dadurch definiert wird, wie er in den Methoden des Objekts angezeigt wird. Ich würde die @param <T>meiste Zeit überspringen und es nur verwenden, wenn es wirklich nicht klar ist.

— Kevin Bourrillion

Ich verstehe, was Sie sagen, aber aus diesem Grund gilt das Gleiche für die Verwendung von @paramMethodenparametern. Die Codierungsstandards von Sun besagen ausdrücklich, dass @paramdies verwendet werden sollte, auch wenn die Bedeutung des Methodenparameters klar ist.

— Skaffman

Darüber hinaus. Eine gute API-Programmierung sollte so selbstdokumentierend wie möglich sein. Bedeutet das, dass eine API keine Dokumentation benötigt? Nein.

— Timo Willemsen

Die Dokumentation von @param enthält Anweisungen für Typparameter. Wohlgemerkt, Oracle könnte dieses Dokument besser bewerben.

— Michael Allan

Antworten:

235

Es sollte einfach so gemacht werden:

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

}

Quelle

— Timo Willemsen
quelle

Doh ... OK, das ist peinlich offensichtlich ... es stellt sich die Frage, warum die JavaSE-Klassen (z Collection ) es nicht verwenden.

— Skaffman

LinkedList verwendet es: java.sun.com/j2se/1.5.0/docs/api/java/util/LinkedList.html

— Timo Willemsen

@skaffman Ein bisschen spät natürlich, aber es wirft die Frage auf, tut es nicht die Frage bitten .

— Thor84no

@ Thor84no Von Ihrem Link: Einige Behörden betrachten die Verwendung von "bittet um die Frage" als eine Art zu sagen, "wirft die Frage auf" oder "weicht der Frage aus" nicht mehr aus, weil sie eine so breite Verwendung erreicht hat.

— Matt R

Es ist eine Schande, dass IntelliJ in diesem Fall wie HTML vervollständigt.

— Snicolas

Ja. Verwenden Sie einfach das @ param-Tag und fügen Sie spitze Klammern um den Typparameter ein.

So was:

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

— Dave DiFranco
quelle