Дескриптор ©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 предоставляет ссылку на дополнительные сведения. Ниже приведены две наиболее употребительные формы этого дескриптора. @see ссылка @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.; /★
Класс, демонстрирующий применение документирующих комментариев.
©author Herbert Schildt
©version 1.2 */ public class SquareNum { I ★ ★
Этот метод возвращает квадрат значения параметра num.
Это описание состоит из нескольких строк. Число строк
не ограничивается.
©param num Значение, которое требуется возвести в квадрат.
©return Квадрат числового значения параметра num. / public double square(double num) { return num num; } I -к -к
Этот метод получает значение, введенное пользователем.
©return Введенное значение типа double.
©exception IOException Исключение при ошибке ввода.
©see IOException / public double getNumber() throws IOException { // создать поток BufferedReader из стандартного потока System.in. InputStreamReader isr = new InputStreamReader(System.in); BufferedReader inData = new BufferedReader(isr); String str; str = inData.readLine (); return (new Double(str)).doubleValue() ; } 6X В этом методе демонстрируется применение метода square().
@param args Не используется.
0exception IOException Исключение при ошибке ввода.
@see IOException */ public static void main(String args[]) throws IOException { SquareNum ob = new SquareNum(); double val; System.out.println("Enter value to be squared: "); val = ob.getNumber(); val = ob.square(val); System.out.println("Squared value is " + val); } }