Читать онлайн «Java: руководство для начинающих (ЛП)». Страница 132

Дескриптор @author описывает автора класса или интерфейса и имеет следующийсинтаксис:@author описаниегде описание, как правило, обозначает имя автора. Для того чтобы сведения, указываемые в поле @author, были включены в результирующий HTML-документ, при вызовеутилиты javadoc из командной строки следует указать параметр -author.Дескриптор {@code}

Дескриптор {@code} позволяет включать в комментарии текст, в том числе и отдельные фрагменты кода. Такой текст будет выводиться специальным шрифтом, используемым для форматирования кода, и не подлежит дальнейшей обработке по правилам форматирования HTML-документов. Этот дескриптор имеет следующий синтаксис:{0code фрагмент_кода}Дескриптор @deprecated

Дескриптор @deprecated указывает на то, что класс, интерфейс или метод не рекомендован к применению. В описание рекомендуется включать дескриптор 0see или{@link}, чтобы уведомить программиста о других возможных решениях. У этого дескриптора имеется следующий синтаксис:@deprecated описаниегде описание обозначает сообщение, описывающее причины, по которым данноеязыковое средство Java не рекомендуется к применению. Дескриптор @deprecatedможно применять для документирования полей, методов, конструкторов, классов иинтерфейсов.Дескриптор {@docRoot}

Дескриптор {@docRoot} указывает путь к корневому каталогу документации.Дескриптор @exception

Дескриптор ©exception описывает исключение, которое может возникнуть при выполнении метода. У него имеется следующий синтаксис:©exception имяисключения пояснениегде имяисключения обозначает полностью определенное имя исключения, апояснение — символьную строку, в которой поясняется, при каких условиях исключение может возникнуть. Дескриптор ©exception можно применять только для документирования методов.Дескриптор {@inheritDoc}

Этот дескриптор наследует комментарии от ближайшего суперкласса.Дескриптор {@link}

Дескриптор {01ink} предоставляет встраиваемую ссылку на дополнительные сведения. У него имеется следующий синтаксис:{01ink пакет.класс#член текст}где пакет. класс#член обозначает имя класса или метода, на который делается встраиваемая ссылка, а текст — символьную строку, отображаемую в виде встраиваемойссылки.Дескриптор {@linkplain}

Дескриптор {01inkplain} вставляет встраиваемую ссылку на другую тему. Этассылка отображается обычным шрифтом. А в остальном данный дескриптор подобендескриптору {01 i n к}.Дескриптор {@literal}

Дескриптор {©literal} позволяет включать текст в комментарии. Этот текстотображается без дополнительной обработки по правилам форматирования HTML-документов. У него имеется следующий синтаксис:©literal описаниегде описание обозначает текст, включаемый в комментарии.Дескриптор @param

Дескриптор @param описывает параметр. У него имеется следующий синтаксис:©parameter имяпараметра пояснениегде имяпараметра обозначает конкретное наименование параметра, а пояснение —поясняемое назначение параметра. Дескриптор ©param можно применять для документирования метода, конструктора, а также обобщенного класса или интерфейса.Дескриптор @return

Дескриптор @return описывает значение, возвращаемое методом. У него имеетсяследующий синтаксис:@return пояснениегде пояснение обозначает тип и назначение возвращаемого значения. Дескриптор@ return применяется только для документирования методов.Дескриптор @see

Дескриптор @see предоставляет ссылку на дополнительные сведения. Ниже приведены две наиболее употребительные формы этого дескриптора[email protected] ссылка@see пакет.класс#член текстВ первой форме ссылка обозначает абсолютный или относительный веб-адрес (URL).А во второй форме пакет. классфчлен обозначает имя элемента, тогда как текст —отображаемые сведения об этом элементе. Параметр текст указывать необязательно, ав его отсутствие отображается элемент, определяемый параметром пакет. класс#член.Имя члена также может быть опущено. Этот дескриптор дает возможность указать ссылку не только на метод или поле, но и на класс или интерфейс. Имя элемента может бытьуказано полностью или частично. Но если имени члена предшествует точка, она должнабыть заменена знаком #.Дескриптор @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

Утилита javadoc читает данные из исходного файла программы на Java и формирует несколько HTML-файлов, содержащих документацию на эту программу. Сведенияо каждом классе помещаются в отдельный файл. В результате выполнения утилитыjavadoc составляется также предметный указатель и дерево иерархии. Кроме того, могут быть сформированы и другие HTML-файлы.Пример применения документирующих

комментариевНиже приведен пример программы, в исходном тексте которой имеются документирующие комментарии. Обратите внимание на то, что каждый такой комментарий непосредственно предшествует описываемому элементу программы. После обработки утилитой javadoc документация на класс SquareNum помещается в файл SquareNum.html.import java.io.;/★