Написание документации для Java проекта: продвинутый уровень

Введение: Почему документация — это код

На начальном уровне разработки Java-проектов документация часто воспринимается как формальность. Однако на продвинутом уровне она превращается в полноценный продукт, который требует архитектурного подхода, автоматизации и строгих стандартов качества. Плохо написанная документация может свести на нет преимущества самого чистого кода, тогда как качественная документация сокращает время онбординга новых разработчиков в 2-3 раза и является единственным источником истины для внешних интеграций.

В этой статье мы рассмотрим продвинутые техники написания документации для Java-проектов, выходящие за рамки простых комментариев. Вы узнаете, как использовать JavaDoc с кастомными тегами, интегрировать документацию в CI/CD, применять AsciiDoc для сложных руководств и автоматически тестировать примеры кода в документации.

1. JavaDoc на стероидах: кастомные теги и Doclet API

Стандартный JavaDoc — это основа, но для продвинутого уровня требуется кастомизация. Например, вы можете создавать собственные теги для документирования бизнес-требований, ссылок на задачи в Jira или версий API.

Создание кастомных тегов

Используйте аннотацию @customTag или конфигурацию в pom.xml (для Maven) для добавления новых тегов. Пример:

/**
 * Выполняет валидацию пользовательского ввода.
 *
 * @businessRule Поле email должно соответствовать RFC 5322
 * @jiraTicket PROJ-1234
 * @since 2.1.0
 * @param input строка для валидации
 * @return true, если ввод корректен
 */
public boolean validateEmail(String input) {
    // реализация
}

Для генерации документации с кастомными тегами добавьте в плагин Maven:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <configuration>
        <tags>
            <tag>
                <name>businessRule</name>
                <placement>a</placement>
                <head>Бизнес-правило</head>
            </tag>
            <tag>
                <name>jiraTicket</name>
                <placement>a</placement>
                <head>Тикет Jira</head>
            </tag>
        </tags>
    </configuration>
</plugin>

Doclet API для генерации нестандартных форматов

Если стандартного HTML недостаточно, напишите свой Doclet. Это позволяет генерировать документацию в формате PDF, Markdown или даже в виде JSON для внешних систем.

public class CustomDoclet extends Doclet {
    @Override
    public boolean run(DocletEnvironment environment) {
        // Получаем все классы
        for (TypeElement element : environment.getIncludedTypeElements()) {
            // Генерируем Markdown или другой формат
            System.out.println("# " + element.getSimpleName());
            for (ExecutableElement method : ElementFilter.methodsIn(element.getEnclosedElements())) {
                System.out.println("## " + method.getSimpleName());
                System.out.println(method.getDocComment());
            }
        }
        return true;
    }
}

Запустите свой Doclet через Maven: mvn javadoc:javadoc -Ddoclet=com.example.CustomDoclet.

2. AsciiDoc: документация как код (Docs-as-Code)

Для сложных руководств, архитектурных описаний и API-справочников JavaDoc не подходит. Здесь на помощь приходит AsciiDoc — текстовый формат, который легко версионируется в Git, поддерживает вставку кода, таблиц, диаграмм и условные блоки.

Интеграция с Maven

Используйте плагин asciidoctor-maven-plugin для сборки документации прямо из репозитория:

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>2.2.2</version>
    <configuration>
        <sourceDirectory>src/docs/asciidoc</sourceDirectory>
        <outputDirectory>target/generated-docs</outputDirectory>
        <attributes>
            <toc>left</toc>
            <icons>font</icons>
        </attributes>
    </configuration>
</plugin>

Пример AsciiDoc-документа с вставкой Java-кода

= Руководство по REST API
:doctype: book
:source-highlighter: coderay

== Аутентификация

Для доступа к API используйте Bearer-токен.

[source,java]
----
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.example.com/v1/users"))
    .header("Authorization", "Bearer " + token)
    .GET()
    .build();
----

.Таблица эндпоинтов
|===
| Метод | Путь | Описание
| GET | /users | Список пользователей
| POST | /users | Создать пользователя
|===

Преимущество: вся документация хранится рядом с кодом, её можно ревьювить в пул-реквестах.

3. Тестирование документации: проверяем примеры кода

Одна из самых частых проблем — примеры кода в документации устаревают. Решение — автоматическое тестирование документации. В Java для этого используются специальные инструменты.

Тестирование JavaDoc с помощью JUnit

Можно написать тесты, которые извлекают примеры из комментариев JavaDoc и выполняют их:

public class DocumentationTest {
    @Test
    public void testJavaDocExamples() throws Exception {
        // Используем reflection для поиска методов с примерами
        Method[] methods = MyClass.class.getMethods();
        for (Method method : methods) {
            String doc = method.getAnnotation(Deprecated.class) != null ? 
                         "deprecated" : method.toGenericString();
            // Проверяем, что пример компилируется
            // (упрощенная логика)
        }
    }
}

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

ArchUnit позволяет проверять, что все публичные методы задокументированы:

@Test
public void allPublicMethodsShouldHaveJavaDoc() {
    JavaClasses classes = new ClassFileImporter().importPackages("com.example");
    
    ArchRule rule = classes()
        .that().arePublic()
        .should(haveSimpleName(".*"))
        .andShould(be