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

Далее описаны некоторые из тегов 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("Привет, сегодня: ");

System.out.println(new Date());

}

}

Использование javadoc:

Для генерации документации необходимо выбрать в меню: Выполнить\Создать документацию Java:

В результате будет сгенерирована документация:

В каталоге проекта появится каталог javadoc со следующим содержимым: