Как пояснялось в главе 1, в Java поддерживаются три вида комментариев. Первые два вида обозначаются символами //и/ /,а третий их вид называется документирующими комментариями. Такие комментарии начинаются символами /* и оканчиваются символами /. Документирующие комментарии позволяют включать сведения о программе в исходный код самой программы. Для извлечения этих сведений и последующего их преобразования в формат HTML-документа служит утилита j avadoc, входящая в состав JDK. Документирующие комментарии — удобный способ документирования прикладных программ. Вам, вероятно, уже встречалась документация, сформированная утилитой j avadoc, поскольку именно такой способ применяется для составления документации на библиотеку Java API.

Дескрипторы javadoc

Утилита 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