Генератор документации Javadoc
1. Что такое Java doc?
Наибольшая проблема, связанная с документированием кода – поддержка этой документации. Если документация и код разделены, возникают трудности, связанные с необходимостью внесения изменений в соответствующие разделы сопроводительной документации всякий раз при изменении программного кода. Среда разработки предлагает решение – связать код с документацией, поместив всё в один файл.
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 – просмотр документации.

Please log in or register to have a possibility to add comment.