Existe uma tag javadoc para documentar parâmetros de tipo genérico?

165

Eu estive examinando a documentação do javadoc no site da Sun, tentando descobrir se há uma tag javadoc que pode ser usada para documentar uma assinatura de tipo genérica de classe ou método.

Algo @typeparamparecido com o habitual @param, mas aplicável a tipos e métodos, por exemplo

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

Suspeito que não exista essa tag - não consigo mencioná-la em nenhum lugar, e os documentos da API do JavaSE não mostram nenhum sinal, mas parece uma omissão estranha. Alguém pode me colocar certo?

skaffman
fonte
7
Para escrever javadocs adequados?
Timo Willemsen
2
Esteja ciente de que, para a maioria das classes, não há realmente nada interessante a dizer sobre o parâmetro type, porque o parâmetro type é essencialmente definido pela forma como aparece nos métodos do objeto. Eu pularia a @param <T>maior parte do tempo e só a usaria quando realmente não estivesse claro.
precisa saber é o seguinte
3
Entendo o que você está dizendo, mas por esse raciocínio, o mesmo se aplica ao uso de @parampara parâmetros de método. Os padrões de codificação da Sun dizem explicitamente que @paramdevem ser usados ​​mesmo que o significado do parâmetro do método seja claro.
skaffman
3
Além disso. Uma boa programação de API deve ser o mais documentada possível. Isso significa que uma API não precisa de documentação? não.
Timo Willemsen
A documentação do @param fornece instruções para os parâmetros de tipo. Lembre-se, a Oracle poderia fazer um trabalho melhor ao anunciar este documento.
Michael Allan

Respostas:

235

Isso deve ser feito assim:

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

}

Fonte

Timo Willemsen
fonte
6
Doh .... OK, isso é embaraçosamente óbvio ... ele faz a pergunta de por que as classes JavaSE (por exemplo Collection) não a usam.
skaffman
9
@skaffman Um pouco tarde, é claro, mas levanta a questão, não a implora .
precisa saber é o seguinte
6
@ Thor84no Do seu link: Algumas autoridades consideram o uso de "implora a pergunta" como uma maneira de dizer "levanta a questão" ou "evita a pergunta" não é mais um erro, porque atingiu um uso tão amplo.
Matt R
8
É uma pena que o IntelliJ conclua como HTML neste caso.
Snicolas
27

Sim. Basta usar a tag @param e incluir colchetes angulares ao redor do parâmetro type.

Como isso:

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