Javadoc

1. Что такое Javadoc?

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

Javadoc — генератор документации в HTML-формате из комментариев исходного кода на Java.

Комментарии документации применяют для документирования:

классов,
интерфейсов,
полей (переменных),
конструкторов,
методов,
пакетов.

В каждом случае комментарий должен находиться перед документируемым элементом.

Утилита javadoc позволяет вставлять HTML теги и использовать специальные ярлыки (дескрипторы) документирования.

HTML теги заголовков не используют, чтобы не нарушать стиль файла, сформированного утилитой.

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

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

2. Список дескрипторов Javadoc

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

3. Генерация файлов

Утилита javadoc в качестве входных данных принимает файл с исходным кодом программы. Генерирует несколько HTML файлов, содержащих документацию по этой программе. Информация о каждом классе будет содержаться в отдельном HTML файле. Кроме того, создается дерево индексов и иерархии. Могут быть сгенерированы и другие HTML файлы.

Ctrl+Q – просмотр документации.