Pro Java: Комментарии документации – Javadoc

Документирование javadoc

При документировании приложения необходима также поддержка документации программы. Если документация и код разделены, то непроизвольно создаются сложности, связанные с необходимостью внесения изменений в соответствующие разделы сопроводительной документации при изменении программного кода.

Как правило, все существующие среды разработки IDE приложений Java предлагают решение по связыванию кода с документацией в процессе разработки с использованием javadoc. Для этого необходимо соответствующим образом написать комментарий к коду, т.е. документировать.

Документирование javadoc

Java комментарии необходимы как для комментирования программы, так и для составления или оформления документации.

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

javadoc — это генератор документации в HTML-формате из комментариев исходного кода Java и определяет стандарт для документирования классов Java. Для создания доклетов и тэглетов, которые позволяют программисту анализировать структуру Java-приложения, javadoc также предоставляет API. В каждом случае комментарий должен находиться перед документируемым элементом.

При написании комментариев к кодам Java используют три типа комментариев :

// однострочный комментарий; /* многострочный комментарий */ /** комментирование документации */

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

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

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

javadoc дескрипторы : @author, @version, @since, @see, @param, @return

Дескриптор Применение Описание
@author Класс, интерфейс Автор
@version Класс, интерфейс Версия. Не более одного дескриптора на класс
@since Класс, интерфейс, поле, метод Указывает, с какой версии доступно
@see Класс, интерфейс, поле, метод Ссылка на другое место в документации
@param Метод Входной параметр метода
@return Метод Описание возвращаемого значения
@exception имя_класса описание Метод Описание исключения, которое может быть послано из метода
@throws имя_класса описание Метод Описание исключения, которое может быть послано из метода
@deprecated Класс, интерфейс, поле, метод Описание устаревших блоков кода
{@link reference} Класс, интерфейс, поле, метод Ссылка
{@value} Статичное поле Описание значения переменной

Форма документирования кода

Документирование класса, метода или переменной начинается с комбинации символов /** , после которого следует тело комментариев; заканчивается комбинацией символов */.

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

/** * Класс продукции со свойствами <b>maker</b> и <b>price</b>. * @autor Киса Воробьянинов * @version 2.1 */ class Product { /** Поле производитель */ private String maker; /** Поле цена */ public double price; /** * Конструктор — создание нового объекта * @see Product#Product(String, double) */ Product() { setMaker(""); price=0; } /** * Конструктор — создание нового объекта с определенными значениями * @param maker — производитель * @param price — цена * @see Product#Product() */ Product(String maker,double price){ this.setMaker(maker); this.price=price; } /** * Функция получения значения поля {@link Product#maker} * @return возвращает название производителя */ public String getMaker() { return maker; } /** * Процедура определения производителя {@link Product#maker} * @param maker — производитель */ public void setMaker(String maker) { this.maker = maker; } }

Для документирования кода можно использовать HTML теги. При использовании ссылочных дескрипторов @see и @link нужно сначала указать имя класса и после символа "#" его метод или поле.

Среда разработки IDE, как правило, помогает программисту "подсветкой" встроенной документации. На следующих рисунках приведены скриншоты всплывающих окон IDE Eclipse.

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

Сценарии ant и javadoc

Для создания документации можно использовать ant.

Пример сценария (задания) ant для формирования документации к приложению MyProject :

<?xml version="1.0" encoding="UTF-8"?> <project name="MyProject.doc" default="create-javadoc" basedir="."> <target name="create-javadoc" description="documentation" depends=""> <property name="app.name" value="MyProject" /> <property name="app.version" value="1.21" /> <property name="app.author" value="AuthorName" /> <property name="app.year" value="2015" /> <property name="dir.package" value="examples.projects.*" /> <property name="dir.src" value="./src" /> <property name="dir.doc" value="./doc" /> <echo message="Create MyProject.doc." /> <mkdir dir="${dir.doc}" /> <javadoc destdir="${dir.doc}" use="true" private="true" author="${app.author}" version="${app.version}" windowtitle="${app.name} API" doctitle="${app.name}" > <fileset dir="${dir.src}" defaultexcludes="yes"> <include name="examples/projects/**"/> </fileset> </javadoc> </target> </project>

Подробная информация формирования документации представлена на странице Javadoc/Javadoc2

Наверх

Экспертная оценка.

Попробуйте найти кого-то вне вашей команды (клиента) и спросите их, что они думают о вашем JavaDoc.

Клиент всегда прав.

Также я могу поделиться с вами некоторыми вещами ниже

Отличное чтение о написании javadoc находится на сайте sun at http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

Лучшее, что я узнал из этого текста, вероятно, что ваш уровень javadoc на уровне класса должен начинаться с «Обеспечивает». Это заставляет вас думать о том, что этот класс предоставляет вашей программе (или миру).

/** и /* в Java Комментарии

Это не редкость для меня, чтобы перепроектировать программное обеспечение, потому что написание javadoc заставило меня подумать «эй, это здесь не нужно!».

Другие практические советы: когда интересен интерес, попробуйте записать его в теге @returns. Не делать этого может означать, что вы вводите материал дважды, один раз в javadoc и один раз после тега @return.

Лучший совет: если вы не знаете, что писать, DONT. парсер Javadoc делает отличную работу по автоматическому генерации getter javadoc, например, но это происходит только тогда, когда вы не добавляли /** */.

Javadoc должен описать, ЧТО ваш метод делает, а не КАК.

Джавадок не твой тодолист. Я пробовал, но для больших проектов это просто не работает.

ответ дан developer 23 марта '11 в 9:41

источникподелиться

.

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

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} могут применяться где угодно.

 

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

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

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

Встроенные дескрипторы (начинаются с фигурной скобки) можно помещать внутри любого описания.

Утилита 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 документацию.

Добавить комментарий

Закрыть меню