Читать «Java: руководство для начинающих» онлайн - страница 375

Приложение Б Применение документирующих комментариев в Java

Как пояснялось в главе 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