JavaDoc и документационные комментарии: полное руководство

Типы комментариев в Java

Java поддерживает три вида комментариев:

Что такое Javadoc?

Javadoc — встроенный в JDK инструмент, генерирующий API-документацию в HTML из исходного кода. Он извлекает doc-комментарии (начинающиеся с /**) перед классами, интерфейсами, методами, полями и конструкторами.

Базовый пример

/**
 * Класс HelloWorld выводит приветствие.
 * <p>
 * Пример использования HTML-тегов внутри комментария.
 *
 * @author Иван Иванов
 * @version 1.0
 * @since 2024-01-15
 */
public class HelloWorld {
    /**
     * Точка входа в программу.
     * @param args аргументы командной строки (не используются)
     */
    public static void main(String[] args) {
        // Обычный комментарий — в документацию не попадает
        System.out.println("Hello, World!");
    }
}

Структура doc-комментария

Документационный комментарий состоит из:

1. Описания — первый фрагмент до первого тега или пустой строки. Используется в сводках.
2. Тегов — специальные инструкции, начинающиеся с @ (блочные) или {@ (встроенные).

Основные теги Javadoc

Пример полноценного документированного класса

package com.example.math;

/**
 * Утилиты для математических вычислений.
 * <p>
 * Потокобезопасен, не хранит состояние.
 *
 * @author Команда разработки
 * @version 2.1
 * @since 1.0
 */
public final class MathUtils {

    private MathUtils() {} // утилитарный класс

    /**
     * Вычисляет факториал числа.
     * <p>
     * Сложность: O(n). Для n > 20 результат переполняет {@code long}.
     *
     * @param n неотрицательное целое число
     * @return n! (факториал)
     * @throws IllegalArgumentException если n < 0
     * @see #factorialIterative(int)
     */
    public static long factorial(int n) {
        if (n < 0) throw new IllegalArgumentException("n должен быть >= 0");
        return (n <= 1) ? 1 : n * factorial(n - 1);
    }

    /**
     * Итеративный вариант факториала.
     * @param n неотрицательное число
     * @return n!
     * @throws IllegalArgumentException если n < 0
     */
    public static long factorialIterative(int n) {
        if (n < 0) throw new IllegalArgumentException("n должен быть >= 0");
        long result = 1;
        for (int i = 2; i <= n; i++) result *= i;
        return result;
    }
}

Генерация документации

Запуск из командной строки:

# Базовая генерация
javadoc -d docs -sourcepath src -subpackages com.example

# С дополнительными опциями
javadoc -d docs -sourcepath src \
    -author -version -private \
    -windowtitle "My Project API" \
    -doctitle "<h1>My Project</h1>" \
    -header "<b>My Project</b>" \
    -footer "<i>© 2024</i>" \
    com.example

Ключевые опции:

• -d — выходная директория.
• -sourcepath — корень исходников.
• -subpackages — рекурсивная обработка пакетов.
• -private / -protected / -package / -public — уровень видимости включаемых членов.
• -author, -version — включать соответствующие теги.

Лучшие практики

• Пишите первый фрагмент (summary) емко: одно предложение, заканчивающееся точкой.
• Используйте HTML-разметку (<p>, <code>, <ul>, <table>) для читаемости.
• Документируйте все public и protected API.
• Избегайте избыточных комментариев («геттер для поля name»).
• Используйте {@code} для кода внутри описаний.
• Ссылки на классы/методы делайте через {@link}.
• Помечайте устаревшие элементы @deprecated с альтернативой.
• Проверяйте генерируемую документацию на предупреждения (broken links, missing tags).

Интеграция с IDE и сборкой

• IntelliJ IDEA / Eclipse / VS Code — отображают Javadoc при наведении (Ctrl+Q / F2).
• Maven: mvn javadoc:javadoc (плагин maven-javadoc-plugin).
• Gradle: задача javadoc (тип Javadoc).
• CI/CD — публикуйте документацию на GitHub Pages, GitLab Pages или внутренний сервер.