Javadoc: генератор документации в Java - Вопросы

Javadoc — генератор документации в формате HTML из специальных комментариев /** ... */ в исходном коде Java. Он входит в JDK как команда javadoc; документация к самой стандартной библиотеке (Java SE API) сгенерирована именно им.

Главная задача Javadoc — чтобы документация не расходилась с кодом. Описание пишется прямо над объявлением, его видно при каждом изменении, его подсказывает IDE, а HTML-версия (страница на каждый класс, списки пакетов, индекс и поиск) пересобирается одной командой.

Комментариями Javadoc документируют классы, интерфейсы, перечисления и записи (record), поля, конструкторы и методы, а также пакеты (файл package-info.java) и модули (module-info.java).

Комментарий начинается с /**, заканчивается */ и ставится непосредственно перед объявлением класса, поля, конструктора или метода — до аннотаций и модификаторов. Обычные комментарии /* ... */ и // javadoc пропускает.

• Основное описание идёт первым. Его первое предложение (до первой точки с пробелом) попадает в сводные таблицы пакета и класса.
• Текст — это HTML: абзацы разделяют <p>, списки — <ul>/<li>; свои заголовки не выше <h2>, потому что <h1> строит сам javadoc. Звёздочки в начале строк отбрасываются.
• Блочные теги (@param, @return и др.) начинаются с @, стоят первыми на строке и идут после описания.
• Встроенные теги ({@code}, {@link}) пишутся в фигурных скобках в любом месте текста.

С Java 23 (JEP 467) комментарий можно писать и на Markdown — строками, начинающимися с ///.

• @param имя описание — параметр метода или конструктора; имя должно совпадать с сигнатурой. Параметр типа — @param <T>.
• @return описание — возвращаемое значение (не для void); с Java 16 есть встроенная форма {@return ...}.
• @throws Класс описание — исключение и условие его выброса, включая unchecked; @exception — старый синоним.
• {@link Класс#член} — ссылка на класс, метод или поле, для метода с параметрами указывают типы: {@link String#indexOf(int)}.
• {@code текст} — код моноширинным шрифтом, сам экранирует <, >, &.
• @deprecated — почему элемент устарел и чем его заменить (вместе с аннотацией @Deprecated).

Реже встречаются @author, @version, @since, @see, {@value} (значение константы), {@inheritDoc} (описание из переопределяемого метода) и {@snippet} (пример кода, с Java 18).

Командой javadoc из JDK: ей передают исходники или пакеты и каталог для результата.

javadoc -d docs -sourcepath src -subpackages com.example -author -version -encoding UTF-8

• -d — куда записать HTML; -sourcepath и -subpackages — где искать исходники и какие пакеты обработать;
• -author, -version — включают теги @author и @version;
• -private — документировать и private-элементы (по умолчанию только public и protected);
• -encoding UTF-8 — кодировка исходников (с JDK 18 UTF-8 по умолчанию).

Результат — index.html, страница на каждый класс, package-summary.html, overview-tree.html, index-all.html, списки устаревших элементов и констант. В Maven то же делают mvn javadoc:javadoc и mvn javadoc:jar (архив для Maven Central), в Gradle — ./gradlew javadoc.

IDE показывает комментарий во всплывающем окне прямо из исходников, без генерации HTML. В IntelliJ IDEA окно Quick Documentation открывается сочетанием Ctrl+Q (Windows, Linux) или F1 (macOS), а также при наведении на имя. Если над методом набрать /** и нажать Enter, IntelliJ IDEA или Eclipse создаст заготовку с @param, @return и @throws по сигнатуре.

Документации библиотеки может не быть, потому что компилятор отбрасывает все комментарии, и в jar с байт-кодом их нет. Нужно подключить исходники или javadoc-архив (*-sources.jar, *-javadoc.jar), например кнопкой Download Sources в IntelliJ IDEA.