Есть ли тег javadoc для документирования параметров универсального типа?

165

Я просматривал документацию javadoc на сайте Sun, пытаясь найти, есть ли тег javadoc, который можно использовать для документирования сигнатуры общего типа класса или метода.

Нечто подобное @typeparam, похожее на обычное @param, но применимое к типам, а также к методам, например

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

Я подозреваю, что такого тега нет - я нигде не могу найти упоминания о нем, и документы API JavaSE не показывают его признаков, но это выглядит как странное упущение. Может кто-нибудь исправить меня?

skaffman
источник
7
Чтобы написать правильный Javadocs?
Тимо Виллемсен
2
Имейте в виду, что для большинства классов действительно нет ничего интересного, чтобы сказать о параметре типа, потому что параметр типа по существу определяется тем, как он появляется в методах объекта. Я пропускаю @param <T>большую часть времени и использую его только тогда, когда это действительно не ясно.
Кевин Бурриллион
3
Я понимаю, что вы говорите, но по тому же принципу то же самое относится и к использованию @paramпараметров метода. Стандарты кодирования Sun явно говорят, что @paramих следует использовать, даже если значение параметра метода понятно.
Скаффман
3
В дополнение к этому. Хорошее программирование API должно быть как можно более самодокументированным. Значит ли это, что API не нуждается в документации? нет.
Тимо Виллемсен
Документация @param дает инструкцию для параметров типа. Имейте в виду, Oracle лучше справится с рекламой этого документа.
Майкл Аллан

Ответы:

235

Это должно быть сделано так:

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

}

Источник

Тимо Виллемсен
источник
6
Доу ... Хорошо, это смущающе очевидно ... оно действительно задает вопрос о том, почему классы JavaSE (например Collection) не используют его, хотя.
Скаффман
6
LinkedList использует его: java.sun.com/j2se/1.5.0/docs/api/java/util/LinkedList.html
Тимо Виллемсен
9
@skaffman Немного поздно, конечно, но это поднимает вопрос, но не задает вопрос .
Thor84no
6
@ Thor84no По вашей ссылке: Некоторые власти считают, что использование «напрашивается на вопрос» как способ сказать «поднимает вопрос» или «уклоняется от вопроса» больше не ошибочно, поскольку оно достигло такого широкого использования.
Мэтт Р
8
Обидно, что IntelliJ завершает как HTML в этом случае.
Сниколас
27

Да. Просто используйте тег @param и включите угловые скобки вокруг параметра type.

Как это:

/**
 *  @param <T> This describes my type parameter
 */
Дейв ДиФранко
источник