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

Приложение БПрименение документирующих комментариев в 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

Дескриптор @author описывает автора класса или интерфейса и имеет следующий синтаксис: @author описание где описание, как правило, обозначает имя автора. Для того чтобы сведения, указываемые в поле @author, были включены в результирующий HTML-документ, при вызове утилиты javadoc из командной строки следует указать параметр -author. Дескриптор {@code}

Дескриптор {@code} позволяет включать в комментарии текст, в том числе и отдельные фрагменты кода. Такой текст будет выводиться специальным шрифтом, используемым для форматирования кода, и не подлежит дальнейшей обработке по правилам форматирования HTML-документов. Этот дескриптор имеет следующий синтаксис: {0code фрагмент_кода} Дескриптор @deprecated

Дескриптор @deprecated указывает на то, что класс, интерфейс или метод не рекомендован к применению. В описание рекомендуется включать дескриптор 0see или {@link}, чтобы уведомить программиста о других возможных решениях. У этого дескриптора имеется следующий синтаксис: @deprecated описание где описание обозначает сообщение, описывающее причины, по которым данное языковое средство Java не рекомендуется к применению. Дескриптор @deprecated можно применять для документирования полей, методов, конструкторов, классов и интерфейсов. Дескриптор {@docRoot}