Как пояснялось в главе 1, в Java поддерживаются три вида комментариев. Первые два вида обозначаются символами //и/* /,а третий их вид называется документирующими комментариями. Такие комментарии начинаются символами /* и оканчиваются символами */. Документирующие комментарии позволяют включать сведения о программе в исходный код самой программы. Для извлечения этих сведений и последующего их преобразования в формат HTML-документа служит утилита j avadoc, входящая в состав JDK. Документирующие комментарии — удобный способ документирования прикладных программ. Вам, вероятно, уже встречалась документация, сформированная утилитой j avadoc, поскольку именно такой способ применяется для составления документации на библиотеку Java API.
Утилита javadoc распознает и обрабатывает в документирующих комментариях следующие дескрипторы
| Дескриптор | Описание |
|---|---|
| @author | Обозначает автора программы |
| {@code} | Отображает данные шрифтом, предназначенным для вывода исходного кода, не выполняя преобразований в формат HTML-документа |
| @deprecated | Указывает на то, что элемент программы не рекомендован к применению |
| {@docRoot} | Указывает путь к корневому каталогу документации |
| @exception | Обозначает исключение, генерируемое методом |
| {@inheritDoc} | Наследует комментарии от ближайшего суперкласса |
| {@link} | Вставляет ссылку на другую тему |
| {@linkplain} | Вставляет ссылку на другую тему, но ссылка отображается тем же шрифтом, что и простой текст |
| {@literal} | Отображает данные, не выполняя преобразований в формат HTML-документа |
| @param | Документирует параметр метода |
| @return | Документирует значение, возвращаемое методом |
| @see | Указывает ссылку на другую тему |
| @serial | Документирует поле, упорядочиваемое по умолчанию |
| @serialData | Документирует данные, записываемые методом writeObject() или writeExternal() |
| @serialField | Документирует компонент ObjectStreamField |
| @since | Обозначает версию, в которой были внесены определенные изменения |
| @throws | То же, что и дескриптор @exception |
| {@value} | Отображает значение константы, которая должна быть определена как поле типа static |
| @version | Обозначает версию класса |
Дескрипторы, начинающиеся с символа @, называются автономными и помечают строку комментариев. А дескрипторы, заключенные в фигурные скобки, называются встраиваемыми и могут быть использованы в других дескрипторах. В документирующих комментариях можно также использовать стандартные HTML-дескрипторы. Но некоторые HTML-дескрипторы, например дескрипторы заголовков, применять не следует, поскольку они могут испортить внешний вид HTML-документа, составляемого утилитой javadoc.
Что касается документирования исходного кода, то документирующие комментарии можно использовать для описания классов, интерфейсов, полей, конструкторов и методов. Но в любом случае документирующие комментарии должны предшествовать непосредственно описываемому элементу исходного кода. Одни дескрипторы, в том числе @see, @since и @deprecated, могут быть использованы для документирования любых элементов исходного кода, а другие — только для документирования соответствующих элементов. Каждый дескриптор документирующих комментариев рассматривается далее по отдельности.
На заметку Документирующие комментарии можно также использовать для составления документации и краткого обзора разрабатываемого пакета, но делается это иначе, чем документирование исходного кода. Подробнее об этом можно узнать из документации на утилиту j avadoc.
Дескриптор @author описывает автора класса или интерфейса и имеет следующий синтаксис:
@author описание
где описание, как правило, обозначает имя автора. Для того чтобы сведения, указываемые в поле @author, были включены в результирующий HTML-документ, при вызове утилиты javadoc из командной строки следует указать параметр -author.
Дескриптор {@code} позволяет включать в комментарии текст, в том числе и отдельные фрагменты кода. Такой текст будет выводиться специальным шрифтом, используемым для форматирования кода, и не подлежит дальнейшей обработке по правилам форматирования HTML-документов. Этот дескриптор имеет следующий синтаксис:
{@code фрагмент_кода}
Дескриптор @deprecated указывает на то, что класс, интерфейс или метод не рекомендован к применению. В описание рекомендуется включать дескриптор 0see или {@link}, чтобы уведомить программиста о других возможных решениях. У этого дескриптора имеется следующий синтаксис:
@deprecated описание
где описание обозначает сообщение, описывающее причины, по которым данное языковое средство Java не рекомендуется к применению. Дескриптор @deprecated можно применять для документирования полей, методов, конструкторов, классов и интерфейсов.
Дескриптор {@docRoot} указывает путь к корневому каталогу документации.
Дескриптор @exception описывает исключение, которое может возникнуть при выполнении метода. У него имеется следующий синтаксис:
@exception имя_исключения пояснение
где имя_исключения обозначает полностью определенное имя исключения, а пояснение — символьную строку, в которой поясняется, при каких условиях исключение может возникнуть. Дескриптор @exception можно применять только для документирования методов.
Этот дескриптор наследует комментарии от ближайшего суперкласса.
Дескриптор {01ink} предоставляет встраиваемую ссылку на дополнительные сведения. У него имеется следующий синтаксис:
{@link пакет.класс#член текст}
где пакет. класс#член обозначает имя класса или метода, на который делается встраиваемая ссылка, а текст — символьную строку, отображаемую в виде встраиваемой ссылки.
Дескриптор {01inkplain} вставляет встраиваемую ссылку на другую тему. Эта ссылка отображается обычным шрифтом. А в остальном данный дескриптор подобен дескриптору {@link}.
Дескриптор {@literal} позволяет включать текст в комментарии. Этот текст отображается без дополнительной обработки по правилам форматирования HTML- документов. У него имеется следующий синтаксис:
@literal описание
где описание обозначает текст, включаемый в комментарии.
Дескриптор @param описывает параметр. У него имеется следующий синтаксис:
@parameter имя_параметра пояснение
где имя_параметра обозначает конкретное наименование параметра, а пояснение — поясняемое назначение параметра. Дескриптор @param можно применять для документирования метода, конструктора, а также обобщенного класса или интерфейса.
Дескриптор @return описывает значение, возвращаемое методом. У него имеется следующий синтаксис:
@return пояснение
где пояснение обозначает тип и назначение возвращаемого значения. Дескриптор @ return применяется только для документирования методов.
Дескриптор @see предоставляет ссылку на дополнительные сведения. Ниже приведены две наиболее употребительные формы этого дескриптора.
@see ссылка
@see пакет.класс#член текст
В первой форме ссылка обозначает абсолютный или относительный веб-адрес (URL). А во второй форме пакет. классфчлен обозначает имя элемента, тогда как текст — отображаемые сведения об этом элементе. Параметр текст указывать необязательно, а в его отсутствие отображается элемент, определяемый параметром пакет. класс#член.
Имя члена также может быть опущено. Этот дескриптор дает возможность указать ссылку не только на метод или поле, но и на класс или интерфейс. Имя элемента может быть указано полностью или частично. Но если имени члена предшествует точка, она должна быть заменена знаком #.
Дескриптор @serial определяет комментарии к полю, упорядочиваемому по умолчанию. У этого дескриптора имеется следующий синтаксис:
@serial описание
где описание обозначает комментарии к данному полю.
Дескриптор @serialData предназначен для документирования данных, которые были записаны с помощью методов writeObject () и writeExternal (). Синтаксис этого дескриптора приведен ниже.
@serialData описание
где описание обозначает комментарии к записанным данным.
Этот дескриптор предназначен для документирования классов, реализующих интерфейс Serializable. Он предоставляет комментарии к компоненту ObjectStreamField. У этого дескриптора имеется следующий синтаксис:
@serialField имя тип описание
где имя и тип обозначают конкретное наименование и тип поля соответственно, а описание — комментарии к этому полю.
Дескриптор @since устанавливает, что данный элемент был внедрен, начиная с указанной версии программы. Синтаксис этого дескриптора приведен ниже.
@since версия
Здесь версия обозначает символьную строку, указывающую версию или выпуск программы, где был внедрен данный элемент.
Дескриптор @throws выполняет те же действия, что и дескриптор @exception.
Этот дескриптор применяется в двух основных формах. В первой форме отображается значение константы, которой предшествует этот дескриптор. Константа должна быть полем типа static. Ниже приведена первая форма этого дескриптора.
{@value}
Во второй форме отображается значение указываемого статического поля. Эта форма выглядит следующим образом:
{@value пакет.класс#член }
где пакет. класс#член обозначает имя статического поля.
Дескриптор (Aversion описывает версию класса. Ниже приведен синтаксис этого дескриптора.
@version информация
Здесь информация обозначает символьную строку, содержащую сведения о версии программы. Как правило, это номер версии, например 2.2. Для того чтобы сведения в поле дескриптора 0 vers ion были включены в результирующий HTML-документ, при вызове утилиты javadoc из командной строки следует указать параметр -version.
После символов /** следует одна или несколько строк с общим описанием класса, интерфейса, переменной или метода. Далее можно ввести любое количество дескрипторов, начинающихся со знака @. Каждый такой дескриптор должен начинаться с новой строки или следовать после одной или нескольких звездочек (*) в начале строки. Несколько однотипных дескрипторов должны быть объединены вместе. Так, если требуется использовать три дескриптора 0see, их следует расположить друг за другом. Встраиваемые дескрипторы (начинающиеся с фигурной скобки) можно применять в любом описании. Ниже приведен пример, демонстрирующий применение документирующих комментариев для описания класса.
/**
* Класс для отображения гистограммы.
* 0author Herbert Schildt
* 0version 3.2
*/
Утилита javadoc читает данные из исходного файла программы на Java и формирует несколько HTML-файлов, содержащих документацию на эту программу. Сведения о каждом классе помещаются в отдельный файл. В результате выполнения утилиты javadoc составляется также предметный указатель и дерево иерархии. Кроме того, могут быть сформированы и другие HTML-файлы.
Ниже приведен пример программы, в исходном тексте которой имеются документирующие комментарии. Обратите внимание на то, что каждый такой комментарий непосредственно предшествует описываемому элементу программы. После обработки утилитой javadoc документация на класс SquareNum помещается в файл SquareNum.html.
import java.io.*;
/**
* Класс, демонстрирующий применение документирующих комментариев.
* @author Herbert Schildt
* @version 1.2
*/
public class SquareNum {
/**
* Этот метод возвращает квадрат значения параметра num.
* Это описание состоит из нескольких строк. Число строк
* не ограничивается.
* @param num Значение, которое требуется возвести в квадрат.
* @return Квадрат числового значения параметра num.
*/
public double square(double num) {
return num * num;
}
/**
* Этот метод получает значение, введенное пользователем.
* @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() ;
}
/** В этом методе демонстрируется применение метода 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);
}
}