Описание параметров

Тег @param – описывает параметр метода или класса.

Синтакис:

@param имя описание

Примеры:

/**

* @param <E> Type of element stored in a list */

public interface List<E> extends Collection<E> {

}

<T, V extends T> V convert(String string, Class<T> type) {

}

Возвращаемое значение

Возвращаемое функцией значение определяется тегом @return

Синтаксис: @return описание

Примеры:

/**

*. . .

*@return found object or null if not found

*/

Object find(Object o)

Генерируемые исключения

Каждое исключение (включая неконтролируемое) должно быть описано тегом @throws

Синтаксис:

@throws класс-исключения описание

Javadoc автоматически сгенерирует для контролируемых исключений текст по шаблону.

Для переопределяющих методов будет скопировано описание исключений из описания класса-родителя

Указание автора и версии

Для класса указывается автор: Синтаксис:

@author Автор

И Версия. Синтаксис: @version версия

Тег @since указывает версию, в которой появился класс, метод и т.п.

Синтаксис: @since версия

Секция «см. также»

Ккомментируемому элементу можно добавить секцию «см. также».

Синтаксис: @see ссылка

Каждая ссылка может быть:

Просто строкой. Пример:

@see "The Java Programming Language»

Гиперссылкой. Пример:

@see <a href="spec.html#section">Java Spec</a>

Ссылкой на элемент документации

Ссылка на документацию имеет синтаксис:

@see package.class#member label

Label – видимы текст комментария.

Пример: @see String#equals(Object) equals

Типичные формы параметров для @see

Ссылка на члены текущего класса @see #field

@see #method(Type, Type,...)

@see #method(Type argname, Type argname,...) @see #constructor(Type, Type,...)

@see #constructor(Type argname, Type argname,...)

Ссылка на члены класса данного пакета, или импортируемых пакетов

@see Class#field

@see Class#method(Type, Type,...)

@see Class#method(Type argname, Type argname,...) @see Class#constructor(Type, Type,...)

@see Class#constructor(Type argname, Type argname,...) @see Class.NestedClass

@see Class

Полная ссылка на члены класса в другом пакете (полная форма)

@see package.Class#field

@see package.Class#method(Type, Type,...) @see package.Class#method(Type argname, Type

argname,...)

@see package.Class#constructor(Type, Type,...) @see package.Class#constructor(Type argname, Type

argname,...)

@see package.Class.NestedClass @see package.Class

@see package

Нежелательные к использованию

Нежелательные к использованию классы, методы, интерфейсы, поля и конструкторы нужно помечать тегом @deprecated.

Синтаксис: @deprecated текст

Пример:

/**

* @deprecated As of JDK 1.1, replaced by {@link

#setBounds(int,int,int,int)}

*/

Используемые в описании теги

В описаниях можно использовать следующие теги:

{@code}

{@docRoot}

{@inheritDoc}

{@link}

{@linkplain}

{@literal}

{@value}

Вставка кода

По-умолчанию весь комментарий транслируется в HTML код как есть.

Для того, чтобы использовать символы <>& можно использовать сущности (<, &gt и т.п.), или разместить текст внутри тега {@code}:

{@code A<B<C}

Тег {@literal} даёт такую же функциональность, но с пропорциональным шрифтом.

Тег {@docRoot}

Тег {@docRoot} предназначен для указания корневого пути к сгенерированной документации.

Пример:

/**

* See the

<a href="{@docRoot}/copyright.html">Copyright</a>. */

Ссылка будет сфорирована на файл copyright.html, находящийся в корневом каталоге документации.