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

165

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

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

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

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

java javadoc

— skaffman
источник

Чтобы написать правильный Javadocs?

— Тимо Виллемсен

Имейте в виду, что для большинства классов действительно нет ничего интересного, чтобы сказать о параметре типа, потому что параметр типа по существу определяется тем, как он появляется в методах объекта. Я пропускаю @param <T>большую часть времени и использую его только тогда, когда это действительно не ясно.

— Кевин Бурриллион

Я понимаю, что вы говорите, но по тому же принципу то же самое относится и к использованию @paramпараметров метода. Стандарты кодирования Sun явно говорят, что @paramих следует использовать, даже если значение параметра метода понятно.

— Скаффман

В дополнение к этому. Хорошее программирование API должно быть как можно более самодокументированным. Значит ли это, что API не нуждается в документации? нет.

— Тимо Виллемсен

Документация @param дает инструкцию для параметров типа. Имейте в виду, Oracle лучше справится с рекламой этого документа.

— Майкл Аллан

Ответы:

235

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

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

}

Источник

— Тимо Виллемсен
источник

Доу ... Хорошо, это смущающе очевидно ... оно действительно задает вопрос о том, почему классы JavaSE (например Collection) не используют его, хотя.

— Скаффман

LinkedList использует его: java.sun.com/j2se/1.5.0/docs/api/java/util/LinkedList.html

— Тимо Виллемсен

@skaffman Немного поздно, конечно, но это поднимает вопрос, но не задает вопрос .

— Thor84no

@ Thor84no По вашей ссылке: Некоторые власти считают, что использование «напрашивается на вопрос» как способ сказать «поднимает вопрос» или «уклоняется от вопроса» больше не ошибочно, поскольку оно достигло такого широкого использования.

— Мэтт Р

Обидно, что IntelliJ завершает как HTML в этом случае.

— Сниколас

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

Как это:

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

— Дейв ДиФранко
источник