Dokka для Kotlin: полное руководство с примерами

Введение в Dokka: что это и зачем нужно

Dokka — это мощный инструмент для генерации документации из исходного кода на языке Kotlin. Разработанный компанией JetBrains, Dokka является официальным решением для создания документации Kotlin-проектов. Он анализирует ваш код, извлекает из него KDoc-комментарии (аналог JavaDoc для Kotlin) и генерирует структурированную документацию в различных форматах: HTML, Markdown, Javadoc и другие.

Зачем нужна Dokka?

• Автоматизация: Вам не нужно вручную писать документацию. Dokka генерирует её на основе вашего кода и комментариев.
• Актуальность: Документация всегда соответствует коду, так как генерируется непосредственно из него.
• Поддержка Kotlin Multiplatform: Dokka отлично работает с мультиплатформенными проектами, объединяя документацию из разных модулей (common, jvm, js, native).
• Гибкость: Вы можете настроить внешний вид, формат вывода и включить/исключить определенные части кода.
• Интеграция: Легко интегрируется с системами сборки Gradle и Maven.

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

Установка Dokka

Dokka не устанавливается через pip или npm, так как это инструмент для экосистемы Kotlin/JVM. Основной способ установки — через систему сборки Gradle (рекомендуется) или Maven.

Установка через Gradle (Kotlin DSL)

// build.gradle.kts
plugins {
    id("org.jetbrains.dokka") version "1.9.20" // Проверьте актуальную версию
}

// Или через apply plugin:
// apply(plugin = "org.jetbrains.dokka")

Установка через Gradle (Groovy DSL)

// build.gradle
plugins {
    id 'org.jetbrains.dokka' version '1.9.20'
}

Установка через Maven

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <version>1.9.20</version>
    <executions>
        <execution>
            <phase>compile</phase>
            <goals><goal>dokka</goal></goals>
        </execution>
    </executions>
</plugin>

Быстрый старт: первый запуск

После подключения плагина, вам нужно написать несколько KDoc-комментариев в вашем коде и запустить задачу Gradle.

Шаг 1: Напишите код с комментариями

// src/main/kotlin/com/example/Calculator.kt

/**
 * Простой калькулятор, выполняющий базовые арифметические операции.
 *
 * @author PythonLib Team
 * @since 1.0.0
 */
class Calculator {

    /**
     * Складывает два целых числа.
     *
     * @param a Первое слагаемое.
     * @param b Второе слагаемое.
     * @return Сумма чисел a и b.
     */
    fun add(a: Int, b: Int): Int = a + b

    /**
     * Делит одно число на другое.
     *
     * @param dividend Делимое.
     * @param divisor Делитель. Не может быть равен нулю.
     * @return Результат деления.
     * @throws IllegalArgumentException если divisor равен нулю.
     */
    fun divide(dividend: Double, divisor: Double): Double {
        if (divisor == 0.0) throw IllegalArgumentException("Divisor cannot be zero")
        return dividend / divisor
    }
}

Шаг 2: Запустите генерацию

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

./gradlew dokkaHtml

После выполнения, документация будет сгенерирована в папке build/dokka/html. Откройте index.html в браузере.

Основные методы и функции Dokka (Gradle API)

Dokka предоставляет богатый API для настройки генерации. Вот основные методы и конфигурации, которые вы будете использовать чаще всего.

1. dokkaHtml — Генерация HTML документации

Что делает: Создает документацию в формате HTML. Это самый популярный формат для публикации.

Параметры: Настраивается через блок dokka {}.

tasks.dokkaHtml.configure {
    // Настройки
}

Пример:

tasks.dokkaHtml.configure {
    moduleName.set("My Awesome Library")
    outputDirectory.set(file("docs"))
}

2. dokkaGfm — Генерация Markdown (GitHub Flavored)

Что делает: Создает документацию в формате Markdown, оптимизированном для GitHub.

Параметры: Аналогичны dokkaHtml.

tasks.dokkaGfm.configure {
    moduleName.set("My Library")
}

3. dokkaJavadoc — Генерация Javadoc-совместимой документации

Что делает: Генерирует документацию в стиле Javadoc. Полезно для Java-потребителей вашей библиотеки.

Параметры: Стандартные.

tasks.dokkaJavadoc.configure {
    moduleName.set("My Library")
}

4. moduleName — Установка имени модуля

Что делает: Задает отображаемое имя вашего модуля в документации.

Параметры: String.

tasks.dokkaHtml.configure {
    moduleName.set("Kotlin SDK v2.0")
}

5. outputDirectory — Установка выходной папки

Что делает: Определяет, куда будет сохранена сгенерированная документация.

Параметры: File или String.

tasks.dokkaHtml.configure {
    outputDirectory.set(file("${buildDir}/my-docs"))
}

6. includeNonPublic — Включение приватных элементов

Что делает: По умолчанию Dokka документирует только публичные (public) и защищенные (protected) элементы. Этот флаг включает приватные (private) и внутренние (internal) элементы.

Параметры: Boolean (по умолчанию false).

tasks.dokkaHtml.configure {
    includeNonPublic.set(true)
}

7. skipDeprecated — Пропуск устаревших элементов

Что делает: Позволяет исключить из документации элементы, помеченные аннотацией @Deprecated.

Параметры: Boolean (по умолчанию false).

tasks.dokkaHtml.configure {
    skipDeprecated.set(true)
}

8. sourceLink — Ссылка на исходный код

Что делает: Добавляет ссылки на исходный код (например, на GitHub) для каждого класса или функции.

Параметры: SourceLinkDefinition.

tasks.dokkaHtml.configure {
    sourceLink {
        localDirectory.set(file("src/main/kotlin"))
        remoteUrl.set(URL("https://github.com/username/repo/tree/main/src/main/kotlin"))
        remoteLineSuffix.set("#L")
    }
}

9. suppressObviousFunctions — Подавление очевидных функций

Что делает: Скрывает из документации очевидные функции, такие как equals(), hashCode(), toString().

Параметры: Boolean (по умолчанию true).

tasks.dokkaHtml.configure {
    suppressObviousFunctions.set(true)
}

10. dokkaSourceSets — Настройка исходных наборов

Что делает: Позволяет детально настроить, какие исходные файлы включать, какие исключать, и задать зависимости.

Параметры: Блок конфигурации DokkaSourceSet.

tasks.dokkaHtml.configure {
    dokkaSourceSets.configureEach {
        includes.from("README.md") // Включить README.md в документацию
        includes.from("Module.md") // Включить дополнительный файл
        sourceRoots.from(file("src/main/kotlin"))
        reportUndocumented.set(true) // Сообщать о недокументированных элементах
    }
}

Реальный практический пример использования

Предположим, вы разрабатываете библиотеку для работы с API погоды. Вот как будет выглядеть полный процесс.

Шаг 1: Исходный код

// src/main/kotlin/com/weather/WeatherClient.kt
package com.weather

/**
 * Клиент для получения данных о погоде.
 *
 * @param apiKey Ключ API для доступа к сервису погоды.
 */
class WeatherClient(private val apiKey: String) {

    /**
     * Получает текущую температуру для указанного города.
     *
     * @param cityName Название города (например, "Moscow").
     * @return Текущая температура в градусах Цельсия.
     * @throws WeatherApiException если запрос к API завершился ошибкой.
     */
    fun getCurrentTemperature(cityName: String): Double {
        // Реализация вызова API
        return 25.0 // Заглушка
    }

    /**
     * Получает прогноз погоды на указанное количество дней.
     *
     * @param cityName Название города.
     * @param days Количество дней для прогноза (1-7).
     * @return Список [WeatherForecast] для каждого дня.
     */
    fun getForecast(cityName: String, days: Int): List<WeatherForecast> {
        // Реализация
        return emptyList()
    }
}

/**
 * Модель данных для прогноза погоды.
 *
 * @property date Дата прогноза.
 * @property temperature Средняя температура.
 * @property condition Описание погоды (солнечно, облачно и т.д.).
 */
data class WeatherForecast(
    val date: String,
    val temperature: Double,
    val condition: String
)

/**
 * Исключение, выбрасываемое при ошибках API погоды.
 *
 * @param message Сообщение об ошибке.
 * @param cause Причина ошибки.
 */
class WeatherApiException(message: String, cause: Throwable? = null) : Exception(message, cause)

Шаг 2: Конфигурация build.gradle.kts

plugins {
    kotlin("jvm") version "1.9.22"
    id("org.jetbrains.dokka") version "1.9.20"
}

group = "com.weather"
version = "1.0.0"

repositories {
    mavenCentral()
}

dependencies {
    testImplementation(kotlin("test"))
}

tasks.dokkaHtml.configure {
    moduleName.set("Weather API Client")
    outputDirectory.set(file("${buildDir}/documentation"))
    includeNonPublic.set(false)
    sourceLink {
        localDirectory.set(file("src/main/kotlin"))
        remoteUrl.set(URL("https://github.com/weather/weather-client/tree/main/src/main/kotlin"))
        remoteLineSuffix.set("#L")
    }
    dokkaSourceSets.configureEach {
        includes.from("README.md")
        reportUndocumented.set(true)
    }
}

Шаг 3: Запуск

./gradlew dokkaHtml

После выполнения, в папке build/documentation появится полноценная HTML-документация с описанием классов, функций, параметров и ссылками на GitHub.

Советы и типичные ошибки

Советы:

• Пишите KDoc везде: Документируйте не только публичные API, но и сложные внутренние функции. Используйте @param, @return, @throws.
• Используйте