русс | укр

Языки программирования

ПаскальСиАссемблерJavaMatlabPhpHtmlJavaScriptCSSC#DelphiТурбо Пролог

Компьютерные сетиСистемное программное обеспечениеИнформационные технологииПрограммирование

Все о программировании


Linux Unix Алгоритмические языки Аналоговые и гибридные вычислительные устройства Архитектура микроконтроллеров Введение в разработку распределенных информационных систем Введение в численные методы Дискретная математика Информационное обслуживание пользователей Информация и моделирование в управлении производством Компьютерная графика Математическое и компьютерное моделирование Моделирование Нейрокомпьютеры Проектирование программ диагностики компьютерных систем и сетей Проектирование системных программ Системы счисления Теория статистики Теория оптимизации Уроки AutoCAD 3D Уроки базы данных Access Уроки Orcad Цифровые автоматы Шпаргалки по компьютеру Шпаргалки по программированию Экспертные системы Элементы теории информации

Java комментарии | Javadoc

Наибольшая проблема, связанная с документированием кода – поддержка этой документации. Если документация и код разделены, возникают трудности, связанные с необходимостью внесения изменений в соответствующие разделы сопроводительной документации всякий раз при изменении программного кода. Среда разработки предлагает решение – связать код с документацией, поместив всё в один файл.

Java комментарии необходимы для комментирования программы и для составления или оформления документации. Существует специальный синтаксис для оформления документации в виде комментариев и инструмент для выделения этих комментариев в удобную форму. Инструмент называется javadoc. Обрабатывая файл с исходным текстом программы, он выделяет помеченную документацию из комментариев и связывает с именами соответствующих классов или методов. Таким образом, затратив минимум усилий на оформления комментариев, можно получить хорошую документацию к программе.

На выходе javadoc получается HTML файл, который можно просмотреть любым веб-обозревателем. Этот инструмент позволяет создавать и поддерживать файлы с исходным текстом программы и, при необходимости, генерировать сопроводительную документацию. Библиотеки Java обычно документируются именно таким способом, именно поэтому при разработке программ удобно использовать JDK с комментированным для javadoc исходным текстом библиотек вместо JRE, где исходники отсутствуют.

Java имеет три типа комментариев. Первые два типа: //... и /*...*/. Третий тип называется комментарием документации. Такой комментарий начинается с последовательности символов /** и заканчивается последовательностью */. Комментарии документации позволяют добавлять в программу информацию о ней самой. С помощью утилиты javadoc (входящей в состав JDK) эту информацию можно извлекать и помещать в НТМL ­файл.

Утилита javadoc позволяет вставлять HTML тэги и использовать специальные ярлыки (дескрипторы) документирования. НТМL тэги заголовков не используют, чтобы не нарушать стиль­файла, сформированного утилитой.

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

Комментарии документации применяют для документирования классов, интерфейсов, полей (переменных), конструкторов и методов. В каждом случае комментарий должен находиться перед документируемым элементом.
Для документирования переменной можно использовать следующие дескрипторы:

@see, @serial, @serialField, {@value}, @deprecated.
Для классов и интерфейсов можно использовать дескрипто­ры:
@see, @author, @deprecated, @param, @version.

Методы можно документировать с помощью дескрипторов:
@see, @return, @param, @deprecated, @throws, @serialData, {@inheritDoc}, @ехсерtiоn.

Дескрипторы {@link}, {@docRoot}, {@code}, {@literal}, @since, {@linkplain} могут применяться где угодно.

 

Общая форма комментариев

После начальной комбинации символов /** располагается текст, являющийся главным описанием класса, переменной или метода. Далее можно вставлять различные дескрипторы. Каждый дескриптор @ должен стоять первым в строке. Несколько дескрипторов одного и того же типа необходимо группировать вместе. Встроенные дескрипторы (начинаются с фигурной скобки) можно помещать внутри любого описания.

Утилита javadoc в качестве входных данных принимает файл с исходным кодом программы. Генерирует несколько НТМL ­файлов, содержащих документацию по этой программе. Информация о каждом классе будет содержаться в отдельном НТМL файле. Кроме того, создается дерево индексов и иерархии. Могут быть сгенерированы и другие НТМL­ файлы.

В среде Eclipse генерировать документацию можно используя команду меню Project/Generate Javadoc...

 

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

@author описание
Документирует автора класса. При вызове утилиты javadoc нужно задать
опцию -author, чтобы включить поле в НТМL документацию.

{@code фрагмент_кода}
Позволяет встраивать в комментарий текст (фрагмент кода). Этот текст будет отображаться с помощью шрифта кода без последующей обработки в НТМL.

@deprecated описание
Определяет, что класс, интерфейс или член класса является устаревшим. Рекомендуется включать дескрипторы @see или {@link} для того, чтобы информировать программиста о доступных альтернативных вариантах. Может использоваться для документирования переменных, методов и классов.

{@docRoot}
Определяет путь к корневому каталогу текущей документации.

@exception имя_исключения пояснение
Описывает исключение для данного метода. Здесь имя_исключения указывает полное имя исключения, а пояснение представляет строку, которая описывает, в каких случаях может возникнуть данное исключение. Может использоваться только для документирования методов.

{@inheritDoc}
Наследует комментарий от непосредственного суперкласса.

{@link пакет.класс#элемент текст}
Встраивает ссылку на дополнительную информацию. При отображении текст (если присутствует) используется в качестве имени ссылки.

{@linkplain пакет.класс#элемент текст}
Встраивает ссылку. Ссылка отображается шрифтом основного текста.

{@literal описание}
Позволяет встраивать текст в комментарий. Этот текст отображается "как есть" без последующей обработки HTML.

@param имя_параметра пояснение
Документирует параметр для метода или параметр-тип для класса или интерфейса. Может использоваться только для документирования метода, конструктора, обобщенного класса или интерфейса.

@return пояснение
Описывает возвращаемое значение метода.

@see ссылка
@see пакет.класс#элемент текст
Обеспечивает ссылку на дополнительную информацию.

@serial описание
Определяет комментарий для поля, сериализируемого по умолчанию.

@serialData описание
Документирует данные, записанные с помощью методов writeObject и writeExternal.

@serialField имя тип описание
Для класса, реализующего Serializable, дескриптор обеспечивает комментарии для компонента ObjectStreamField. Здесь имя представляет имя поля, тип представляет его тип, а описание – комментарий для данного поля.

@since выпуск
Показывает, что класс или элемент класса был впервые представлены в определенном выпуске. Здесь выпуск представляет строку, в которой указан выпуск или версия, начиная с которого эта особенность стала доступной.

@throws имя_исключения пояснение
Имеет то же назначение, что и дескриптор @exception.

{@value}
Отображает значение следующей за ним константы, которой должно являться поле static.

{@value пакет.класс#поле}
Отображает значение определенного поля static.

@version информация
Представляет информацию о версии (как правило, номер). При выполнении утилиты javadoc нужно указать опцию -version, чтобы этот дескриптор включить в НТМL документацию.

Просмотров: 20787

Вернуться воглавление


Карта сайта Карта сайта укр


Уроки php mysql Программирование

Онлайн система счисления Калькулятор онлайн обычный Инженерный калькулятор онлайн Замена русских букв на английские для вебмастеров Замена русских букв на английские

Аппаратное и программное обеспечение Графика и компьютерная сфера Интегрированная геоинформационная система Интернет Компьютер Комплектующие компьютера Лекции Методы и средства измерений неэлектрических величин Обслуживание компьютерных и периферийных устройств Операционные системы Параллельное программирование Проектирование электронных средств Периферийные устройства Полезные ресурсы для программистов Программы для программистов Статьи для программистов Cтруктура и организация данных


 


Полезен материал? Поделись:

Не нашли то, что искали? Google вам в помощь!

 
 

© life-prog.ru При использовании материалов прямая ссылка на сайт обязательна.