Урок 21

Javadoc

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

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

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

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

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

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

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

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

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

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

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

Дескриптор

Описание

Применим к

@author

Автор

класс, интерфейс

@version

Версия. Не более одного дескриптора на класс.

класс, интерфейс

@since

Указывает, с какой версии доступно.

класс, интерфейс, поле, метод

@see

Ссылка на другое место в документации.

класс, интерфейс, поле, метод

@param

Входной параметр метода.

метод

@return

Описание возвращаемого значения.

метод

@deprecated

Описание устаревших блоков кода.

класс, интерфейс, поле, метод

{@link reference}

Ссылка.

класс, интерфейс, поле, метод

{@value}

Описание значения переменной.

статичное поле

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

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

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

 

Generate JavaDoc Dialog




0 comments
Leave your comment: