Java руководство для начинающих - Шилдт Герберт (2012)

А во второй форме пакет. классфчлен обозначает имя элемента, тогда как текст —

отображаемые сведения об этом элементе. Параметр текст указывать необязательно, а

в его отсутствие отображается элемент, определяемый параметром пакет. класс#член.

Имя члена также может быть опущено. Этот дескриптор дает возможность указать ссылку не только на метод или поле, но и на класс или интерфейс. Имя элемента может быть

указано полностью или частично. Но если имени члена предшествует точка, она должна

быть заменена знаком #.

Дескриптор @serial

Дескриптор @serial определяет комментарии к полю, упорядочиваемому по умолчанию. У этого дескриптора имеется следующий синтаксис:

@serial описание

где описание обозначает комментарии к данному полю.

Дескриптор @serialData

Дескриптор @serialData предназначен для документирования данных, которые

были записаны с помощью методов writeObject () и writeExternal (). Синтаксис

этого дескриптора приведен ниже.

QserialData описание

где описание обозначает комментарии к записанным данным.

Дескриптор @serialField

Этот дескриптор предназначен для документирования классов, реализующих интерфейс Serializable. Он предоставляет комментарии к компоненту

ObjectStreamField. У этого дескриптора имеется следующий синтаксис:

0serialField имя тип описание

где имя и тип обозначают конкретное наименование и тип поля соответственно, а

описание — комментарии к этому полю.

Дескриптор @since

Дескриптор @since устанавливает, что данный элемент был внедрен, начиная с указанной версии программы. Синтаксис этого дескриптора приведен ниже.

0since версия

Здесь версия обозначает символьную строку, указывающую версию или выпуск программы, где был внедрен данный элемент.

Дескриптор @throws

Дескриптор @throws выполняет те же действия, что и дескриптор @exception.

Дескриптор @value

Этот дескриптор применяется в двух основных формах. В первой форме отображается значение константы, которой предшествует этот дескриптор. Константа должна быть

полем типа static. Ниже приведена первая форма этого дескриптора.

{@value}

Во второй форме отображается значение указываемого статического поля. Эта форма

выглядит следующим образом:

{@value пакет.класс#член }

где пакет. класс#член обозначает имя статического поля.

Дескриптор @version

Дескриптор (Aversion описывает версию класса. Ниже приведен синтаксис этого дескриптора.

0 vers ion информация

Здесь информация обозначает символьную строку, содержащую сведения о версии

программы. Как правило, это номер версии, например 2.2. Для того чтобы сведения в

поле дескриптора 0 vers ion были включены в результирующий HTML-документ, при

вызове утилиты javadoc из командной строки следует указать параметр -version.

Общая форма документирующих комментариев

После символов / следует одна или несколько строк с общим описанием класса,

интерфейса, переменной или метода. Далее можно ввести любое количество дескрипторов, начинающихся со знака @. Каждый такой дескриптор должен начинаться с новой строки или следовать после одной или нескольких звездочек (*) в начале строки.

Несколько однотипных дескрипторов должны быть объединены вместе. Так, если требуется использовать три дескриптора 0see, их следует расположить друг за другом.

Встраиваемые дескрипторы (начинающиеся с фигурной скобки) можно применять

в любом описании.

Ниже приведен пример, демонстрирующий применение документирующих комментариев для описания класса.

/

Класс для отображения гистограммы.

0author Herbert Schildt

0version 3.2

*/

Результат, выводимый утилитой javadoc