Хватит писать документацию вручную — глубокий обзор Dokka

Знакомая ситуация? Проект растет, команда расширяется, а документация... ну, она где-то есть. Возможно, в Confluence, и последний раз её обновляли полгода назад. Код давно ускакал вперед, и новые разработчики тратят часы, пытаясь понять, как работает тот или иной модуль. А что, если я скажу, что ваша документация может писаться практически сама, прямо из кода, и всегда оставаться актуальной?

Сегодня мы поговорим о Dokka — официальном инструменте для генерации документации от JetBrains, создателей Kotlin. Это не просто "еще один Javadoc", а мощный и гибкий движок, который может серьезно облегчить жизнь любой Kotlin-команде.

Что такое Dokka и зачем она нужна?

Если коротко, Dokka — это генератор документации, который читает комментарии в вашем коде (KDoc для Kotlin и Javadoc для Java) и превращает их в удобный для чтения формат. По сути, это Javadoc на стероидах, созданный для современного мира Kotlin, но не забывающий о своих Java-корнях.

Зачем это нужно?

Актуальность: Документация живет рядом с кодом. Изменили метод — поправили комментарий. Это гораздо проще, чем лезть в отдельную вики-систему.
Автоматизация: Одна команда в консоли — и у вас готов красивый, интерактивный сайт с описанием всего вашего API.
Единообразие: Все модули и библиотеки компании могут иметь документацию в едином, привычном стиле.

Кстати, Dokka используют такие гиганты, как kotlinx.coroutines, Ktor, OkHttp и даже Gradle для своего Kotlin DSL. Это уже говорит о многом.

Ключевые возможности, которые цепляют

Dokka — это не просто парсер комментариев. В ней есть несколько киллер-фич, которые делают её незаменимой для многих проектов.

1. Понимает и Kotlin, и Java

Пожалуй, главная боль в разработке (особенно в Android) — это проекты, где новый код на Kotlin соседствует с легаси на Java. Dokka элегантно решает эту проблему. Ей абсолютно всё равно, пишете вы KDoc для Kotlin-класса или старый добрый Javadoc для Java-интерфейса. Она поймет и то, и другое, собрав всё в единый, консистентный документ. Больше не нужно двух разных инструментов или костылей.

2. Гибкость на выходе: HTML, Markdown и даже Javadoc

Dokka не загоняет вас в рамки одного формата. В зависимости от ваших задач, вы можете сгенерировать:

Современный HTML-сайт. Это формат по умолчанию. Получается красивый, адаптивный сайт с поиском, удобной навигацией и подсветкой синтаксиса. Отличный пример — документация kotlinx.coroutines.
Markdown. Dokka умеет генерировать документацию в форматах GitHub Flavored Markdown и Jekyll. Это невероятно удобно, если вы хотите встроить документацию прямо в GitHub Wiki вашего проекта или на статический сайт.
Классический Javadoc. Если ваша команда или ваши пользователи привыкли к стандартному виду Javadoc-документации, не проблема. Dokka может мимикрировать под классический формат, при этом переводя сигнатуры Kotlin в Java-вид.

3. Простая интеграция в сборку

Никаких танцев с бубном и сложных конфигурационных файлов. Интеграция Dokka в проект занимает буквально пару минут.

Для Gradle (Kotlin DSL) достаточно добавить плагин в build.gradle.kts:

plugins {
    id("org.jetbrains.dokka") version "2.1.0"
}

После этого запускаете задачу dokkaHtml, и в папке build/dokka/html вас ждет готовый сайт. Серьезно, это почти всё, что нужно для старта.

Для Maven процесс не сложнее — добавляем плагин в pom.xml:

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <version>2.1.0</version>
    <executions>
        <execution>
            <phase>pre-site</phase>
            <goals>
                <goal>dokka</goal>
            </goals>
        </execution>
    </executions>
</plugin>

И выполняем dokka:dokka. Просто и эффективно.

4. Расширяемость через плагины

А что, если стандартных возможностей не хватает? Dokka построена на плагинной архитектуре. Это значит, что вы можете настраивать и расширять её функциональность.

Например, есть специальный плагин для Android-разработчиков. Он помогает лучше интегрироваться с особенностями Android-проектов и генерировать более релевантную документацию. Подключить его так же просто:

dependencies {
    dokkaPlugin("org.jetbrains.dokka:android-documentation-plugin:2.1.0")
}

Хотите добавить поддержку диаграмм Mermaid или кастомизировать HTML-шаблон? Скорее всего, для этого уже есть плагин, или вы можете написать свой.

Как это выглядит на практике?

Давайте представим жизненный цикл работы с Dokka.

Вы пишете код. Как обычно, но теперь добавляете осмысленные KDoc-комментарии к публичным классам и методам. Объясняете, что делает функция, какие параметры принимает и что возвращает.
Настраиваете сборку. Один раз добавляете плагин Dokka в ваш build.gradle или pom.xml.
Генерируете документацию. Перед релизом новой версии библиотеки или просто для внутреннего использования вы запускаете одну Gradle-команду: ./gradlew dokkaHtml.
Публикуете результат. Dokka создает в папке build/dokka готовый статический сайт. Вам остается только выложить его на GitHub Pages, GitLab Pages или любой другой хостинг.

Весь процесс легко встраивается в CI/CD. Ваша документация будет обновляться автоматически при каждом релизе.

Кому стоит попробовать Dokka?

Dokka — это инструмент, который будет полезен практически любому Kotlin-разработчику, но есть категории, для которых он просто незаменим:

Авторам библиотек и фреймворков. Для вас хорошая документация — это лицо проекта. Dokka поможет создать её профессионально и без лишних усилий.
Командам, работающим над большими продуктами. Когда над проектом трудится много людей, документация на внутренние API, модули и сервисы становится критически важной.
Android-разработчикам. Учитывая смешанную кодовую базу (Java/Kotlin) и наличие специального плагина, Dokka — идеальный выбор для Android-проектов.
Всем, кто пишет код, который будут читать другие (или он сам через полгода).

Dokka — это не просто генератор документации. Это инструмент, который может изменить культуру документирования в команде. Он максимально снижает порог входа, делая процесс создания и поддержки документации почти незаметным и автоматическим.

Если вы пишете на Kotlin и цените свое время и время своих коллег, обязательно дайте Dokka шанс. Начните с небольшого модуля или pet-проекта, и, я уверен, вы быстро оцените, насколько проще и приятнее стала работа с кодом.

Загляните в официальную документацию и присоединяйтесь к обсуждению в канале #dokka в Kotlin Community Slack.