Czy istnieje znacznik javadoc do dokumentowania parametrów typu ogólnego?

165

Przeglądałem dokumentację javadoc w witrynie Sun, próbując znaleźć znacznik javadoc, który może być użyty do udokumentowania ogólnego podpisu typu klasy lub metody.

Coś podobnego @typeparam, podobnego do zwykłego @param, ale pasującego do typów i metod, np

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

Podejrzewam, że nie ma takiego tagu - nigdzie nie mogę znaleźć o nim wzmianki, a dokumentacja JavaSE API nie wykazuje żadnego znaku, ale wydaje się, że jest to dziwne pominięcie. Czy ktoś może mnie naprawić?

skaffman
źródło
7
Pisać poprawne javadoc?
Timo Willemsen,
2
Należy pamiętać, że dla większości klas naprawdę nie ma nic ciekawego do powiedzenia na temat parametru typu, ponieważ parametr typu jest zasadniczo zdefiniowany przez sposób, w jaki pojawia się w metodach obiektu. Pomijałbym @param <T>większość czasu i używam go tylko wtedy, gdy jest naprawdę niejasny.
Kevin Bourrillion
3
Rozumiem, co mówisz, ale z tego powodu to samo dotyczy użycia @paramparametrów metody for. Standardy kodowania firmy Sun wyraźnie mówią, że @parampowinno się to stosować, nawet jeśli znaczenie parametru metody jest jasne.
skaffman
3
W dodatku. Dobre programowanie API powinno być tak samo dokumentujące, jak to tylko możliwe. Czy to oznacza, że ​​api nie potrzebuje dokumentacji? Nie.
Timo Willemsen
Dokumentacja @param daje instrukcje dotyczące parametrów typu. Pamiętaj, że Oracle może lepiej zareklamować ten dokument.
Michael Allan

Odpowiedzi:

235

Należy to zrobić tak:

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

}

Źródło

Timo Willemsen
źródło
6
Doh ... OK, to żenująco oczywiste ... nasuwa się jednak pytanie, dlaczego klasy JavaSE (np. Collection) Go nie używają.
skaffman
6
LinkedList używa go: java.sun.com/j2se/1.5.0/docs/api/java/util/LinkedList.html
Timo Willemsen
9
@skaffman Trochę za późno, oczywiście, ale rodzi pytanie, nie nasuwa pytanie .
Thor84no
6
@ Thor84no Z twojego linku: Niektóre autorytety uważają, że użycie „prosi o pytanie” jako sposobu na powiedzenie „stawia pytanie” lub „wymyka się pytaniu” nie jest już błędne, ponieważ stało się tak szerokie.
Matt R
8
Szkoda, że ​​IntelliJ w tym przypadku uzupełnia jak HTML.
Snicolas
27

Tak. Po prostu użyj tagu @param i umieść nawiasy ostre wokół parametru type.

Lubię to:

/**
 *  @param <T> This describes my type parameter
 */
Dave DiFranco
źródło