Java: руководство для начинающих

Утилита javadoc распознает и обрабатывает в документирующих комментариях следующие дескрипторы

Дескриптор Описание @author Обозначает автора программы {0code} Отображает данные шрифтом, предназначенным для вывода исходного кода, не выполняя преобразований в формат HTML-документа @deprecated Указывает на то, что элемент программы не рекомендован к применению {0docRoot} Указывает путь к корневому каталогу документации Gexception Обозначает исключение, генерируемое методом {@inheritDoc} Наследует комментарии от ближайшего суперкласса {@link} Вставляет ссылку на другую тему {@linkplain} Вставляет ссылку на другую тему, но ссылка отображается тем же шрифтом, что и простой текст {@literal} Отображает данные, не выполняя преобразований в формат HTML-документа @param Документирует параметр метода @return Документирует значение, возвращаемое методом @see Указывает ссылку на другую тему 0serial Документирует поле, упорядочиваемое по умолчанию QserialData Документирует данные, записываемые методом writeObject или writeExternal @serialField Документирует компонент ObjectStreamField 0since Обозначает версию, в которой были внесены определенные изменения @throws То же, что и дескриптор @exception {@value} Отображает значение константы, которая должна быть определена как поле типа static (Aversion Обозначает версию класса Дескрипторы, начинающиеся с символа @, называются автономными и помечают строку комментариев. А дескрипторы, заключенные в фигурные скобки, называются Приложение Б. Применение документирующих комментариев в Java 6Q5 встраиваемыми и могут быть использованы в других дескрипторах. В документирующих комментариях можно также использовать стандартные HTML-дескрипторы. Но некоторые HTML-дескрипторы, например дескрипторы заголовков, применять не следует, поскольку они могут испортить внешний вид HTML-документа, составляемого утилитой javadoc. Что касается документирования исходного кода, то документирующие комментарии можно использовать для описания классов, интерфейсов, полей, конструкторов и методов. Но в любом случае документирующие комментарии должны предшествовать непосредственно описываемому элементу исходного кода. Одни дескрипторы, в том числе @see, @since и @deprecated, могут быть использованы для документирования любых элементов исходного кода, а другие — только для документирования соответствующих элементов. Каждый дескриптор документирующих комментариев рассматривается далее по отдельности. На заметку Документирующие комментарии можно также использовать для составления документации и краткого обзора разрабатываемого пакета, но делается это иначе, чем документирование исходного кода. Подробнее об этом можно узнать из документации на утилиту j avadoc. Дескриптор @author

Дескриптор @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 предоставляет ссылку на дополнительные сведения. Ниже приведены две наиболее употребительные формы этого дескриптора. @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, их следует расположить друг за другом. Встраиваемые дескрипторы (начинающиеся с фигурной скобки) можно применять в любом описании. Ниже приведен пример, демонстрирующий применение документирующих комментариев для описания класса. /