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

Инструмент для извлечения комментариев называется 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-код поддерживается всеми типами документации в комментариях — для классов, переменных или методов.