Документация в комментариях

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

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

Синтаксис

Все команды javadoc находятся только внутри комментариев /**. Комментарии, как обычно, завершаются последовательностью */. Существует два основных способа работы с javadoc: встраивание HTML-текста или использование разметки документации (тегов).

Самостоятельные теги документации — это команды, которые начинаются символом @ и размещаются с новой строки комментария. (Начальный символ игнорируется.) Встроенные теги документации могут располагаться в любом месте комментария javadoc, также начинаются со знака @, но должны заключаться в фигурные скобки.

Существует три вида документации в комментариях: для разных элементов кода:

- класса,

- переменной

- метода.

Комментарий к классу записывается прямо перед его определением; комментарий к переменной размещается непосредственно перед ее определением, а комментарий к методу тоже записывается прямо перед его определением. Простой пример:

/** Комментарий к классу */

public class Documentation1 {

/** Комментарий к переменной */

public int;

/** Комментарий к методу */

public void f() {}

}

Если записать комментарий /**…*/ в другой части кода, то ошибки не будет, но он не попадет в документацию, генерируемую javadoc. Заметьте, что javadoc обрабатывает документацию в комментариях только для членов класса с уровнем доступа public и protected. Комментарии для членов private и членов с доступом в пределах пакета игнорируются, и документация по ним не строится. (Впрочем, флаг -private включает обработку и этих членов). Это вполне логично, поскольку только public- и protected-члены доступны вне файла, и именно они интересуют программиста-клиента. Результатом работы программы является HTML-файл в том же формате, что и остальная документация для Java, так что пользователям будет привычно и удобно просматривать и вашу документацию.

Встроенный HTML

Javadoc вставляет команды HTML в итоговый документ. Это позволяет полностью использовать все возможности HTML; впрочем, данная возможность, прежде всего, ориентирована на форматирование кода:

/**

<рге>

System out print! n(new DateO);

</pre>

Вы можете использовать HTML точно так же, как в обычных страницах, чтобы привести описание к нужному формату:

/**

Можно <em>даже</em> вставить список:

<ol>

<li> Пункт первый

<li> Пункт второй

<li> Пункт третий

</ol>

Javadoc игнорирует звездочки в начале строк, а также начальные пробелы. Текст переформатируется таким образом, чтобы он отвечал виду стандартной документации. Не используйте заголовки вида <hl> или <h2> во встроенном HTML, потому что javadoc вставляет свои собственные заголовки и ваши могут с ними «пересечься». Встроенный HTML-код поддерживается всеми типами документации в комментариях — для классов, переменных или методов.

Примеры тегов

Далее описаны некоторые из тегов javadoc, используемых при документировании программы.

@see: ссылка на другие классы

Тег позволяет ссылаться на документацию к другим классам. Там, где были записаны теги @see, Javadoc создает HTML-ссылки на другие документы. Основные формы использования тега:

@see имя класса

@see полное-имя-класса

@see полное-имя-класса#имя-метода

Примеры:

@see java.lang.String

@see java.lang.Math#PI

@see <a href=”java.sun.com”>Official Java site</a>

Каждая из этих форм включает в генерируемую документацию замечание See Also («см. также») со ссылкой на указанные классы. Javadoc не проверяет передаваемые ему гиперссылки.

{@link пакет.класс#член_класса метка}

Тег очень похож на @see, не считая того, что он может использоваться как встроенный, а вместо стандартного текста See Also в ссылке размещается текст, указанный в поле метка.

{@docRoot}

Позволяет получить относительный путь к корневой папке, в которой находится документация. Полезен при явном задании ссылок на страницы из дерева документации.

{@inheritDoc}

Наследует документацию базового класса, ближайшего к документируемому классу, в текущий файл с документацией.

Version

Имеет следующую форму:

@version информация-о-версии

Поле информации о версии содержит ту информацию, которую вы сочли нужным включить. Когда в командной строке javadoc указывается опция -version, в созданной документации специально отводится место, заполняемое информацией о версиях.

Author

Записывается в виде

@author информация-об-авторе

Предполагается, что поле информация-об-авторе представляет собой имя автора, хотя в него также можно включить адрес электронной почты и любую другую информацию. Когда в командной строке javadoc указывается опция -author, в созданной документации сохраняется информация об авторе.

Для создания списка авторов можно записать сразу несколько таких тегов, но они должны размещаться последовательно. Вся информация об авторах объединяется в один раздел в сгенерированном коде HTML.

Since

Тег позволяет задать версию кода, с которой началось использование некоторой возможности. В частности, он присутствует в HTML-документации по Java, где служит для указания версии JDK.

Param

Полезен при документировании методов. Форма использования:

@param имя-параметра описание

где имя-параметра — это идентификатор в списке параметров метода, а описание — текст описания, который можно продолжить на несколько строк. Описание считается завершенным, когда встретится новый тег. Можно записывать любое количество тегов @param, по одному для каждого параметра метода.

Return

Форма использования:

@return описание

где описание объясняет, что именно возвращает метод. Описание может состоять из нескольких строк.

Throws

Хотя при вызове метода создается всегда один объект исключения, определенный метод может вырабатывать произвольное количество исключений, и все они требуют описания. Соответственно, форма тега исключения такова:

@throws полное-имя-класса описание

где полное-имя-класса дает уникальное имя класса исключения, который где-то определен, а описание (расположенное на произвольном количестве строк) объясняет, почему данный метод способен создавать это исключение при своем вызове.

Deprecated

Тег используется для пометки устаревших возможностей, замещенных новыми и улучшенными. Он сообщает о том, что определенные средства программы не следует использовать, так как в будущем они, скорее всего, будут убраны. В Java SE5 тег @deprecated был заменен директивой @Deprecated

Пример простейшей программы со встроенной документацией:

/** Первая программа

* Выводит строку и текущее число.

* @author Брюс Эккель

* @author www.MindView net

* @version 4.0

public class HelloDate {

/** Точка входа в класс и приложение

* @param args Массив строковых аргументов

* @throws exceptions Исключения не выдаются

public static void main(String[] args) {

System.out.prinln("Привет, сегодня: ");