Брюс Эккель - Философия Java3

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

//. object/Documentationl.java /** Комментарий к классу */ public class Documentationl {

/** Комментарий к переменной */ public int i:

/** Комментарий к методу */ public void f() {} } ///-

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

Результатом работы программы является HTML-файл в том же формате, что и остальная документация для Java, так что пользователям будет привычно и удобно просматривать и вашу документацию. Попробуйте набрать текст предыдущего примера, «пропустите» его через javadoc и просмотрите полученный HTML-файл, чтобы увидеть результат.

Встроенный HTML

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

II: object/Documentation2.java

*

III:-

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

II: object/Documentation3.java /**

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

*

*

1. Пункт первый

   *

2. Пункт второй

   *

3. Пункт третий

   *

///:-

Javadoc игнорирует звездочки в начале строк, а также начальные пробелы. Текст переформатируется таким образом, чтобы он отвечал виду стандартной документации. Не используйте заголовки вида или

во встроенном HTML, потому что javadoc вставляет свои собственные заголовки и ваши могут с ними «пересечься».

Встроенный HTML-код поддерживается всеми типами документации в комментариях — для классов, переменных или методов.

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

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

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

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

@see имя класса

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

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

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

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

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

{@docRoot}

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

{@inheritDoc}

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

@version

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

(Pversion информация-о-версии

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

@author

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

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

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

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

@since

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