Написание документации для Kotlin проекта: от А до Я

Введение: почему документация важна для Kotlin проекта

Написание документации — это не просто формальность, а ключевой элемент успешного Kotlin проекта. Хорошо документированный код ускоряет онбординг новых разработчиков, упрощает поддержку и снижает количество ошибок. Kotlin, будучи современным языком, предлагает мощные инструменты для создания документации: KDoc (аналог JavaDoc) и Dokka (генератор документации). В этой статье мы разберем полный цикл написания документации для Kotlin проекта: от комментариев в коде до публикации готовой документации.

Независимо от того, работаете ли вы над библиотекой, API или внутренним приложением, следование лучшим практикам документирования сделает ваш код понятным и доступным. Давайте начнем с основ.

Основы KDoc: синтаксис и структура

KDoc — это язык разметки для документирования Kotlin кода. Он основан на JavaDoc, но адаптирован под особенности Kotlin: null-безопасность, функции-расширения, свойства и лямбды. Комментарии KDoc начинаются с /** и заканчиваются */.

Базовая структура KDoc-комментария

Каждый KDoc-комментарий состоит из описания и необязательных тегов. Основные теги:

• @param — описание параметра функции
• @return — описание возвращаемого значения
• @throws или @exception — описание исключения
• @see — ссылка на другой элемент
• @sample — вставка примера кода
• @property — описание свойства класса
• @constructor — описание конструктора
• @receiver — описание получателя для функций-расширений

Пример простого KDoc-комментария:

/**
 * Вычисляет факториал заданного числа.
 *
 * Использует итеративный подход для избежания переполнения стека.
 * Работает только с неотрицательными целыми числами.
 *
 * @param n Неотрицательное целое число, для которого вычисляется факториал
 * @return Факториал числа n (n!)
 * @throws IllegalArgumentException если n < 0
 */
fun factorial(n: Int): Long {
    require(n >= 0) { "n must be non-negative" }
    var result = 1L
    for (i in 2..n) {
        result *= i
    }
    return result
}

Документирование свойств и классов

Для классов и свойств используйте тег @property:

/**
 * Представляет пользователя системы.
 *
 * @property id Уникальный идентификатор пользователя
 * @property name Полное имя пользователя
 * @property email Адрес электронной почты
 * @property isActive Флаг активности аккаунта
 */
data class User(
    val id: Long,
    val name: String,
    val email: String,
    val isActive: Boolean = true
)

Генерация документации с помощью Dokka

Dokka — это официальный инструмент для генерации документации Kotlin. Он поддерживает несколько форматов вывода: HTML, Markdown, Javadoc и JSON. Dokka умеет обрабатывать мультиплатформенные проекты и корректно отображает Kotlin-specific конструкции.

Настройка Dokka в Gradle

Чтобы добавить Dokka в проект, подключите плагин в build.gradle.kts:

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

tasks.dokkaHtml {
    outputDirectory.set(buildDir.resolve("dokka"))
    moduleName.set("My Kotlin Library")
}

tasks.dokkaJavadoc {
    outputDirectory.set(buildDir.resolve("javadoc"))
}

После этого выполните команду ./gradlew dokkaHtml — документация будет сгенерирована в папку build/dokka.

Продвинутые возможности Dokka

Dokka поддерживает кастомизацию внешнего вида, включение/исключение пакетов и добавление дополнительных страниц. Пример настройки с кастомным логотипом:

tasks.dokkaHtml {
    dokkaSourceSets {
        named("main") {
            includes.from("README.md")
            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl.set(uri("https://github.com/user/repo/tree/main/src/main/kotlin"))
                remoteLineSuffix.set("#L")
            }
        }
    }
    pluginsConfiguration.html {
        customAssets.setFrom(file("logo.png"))
    }
}

Лучшие практики документирования Kotlin кода

Чтобы ваша документация была полезной и читаемой, следуйте этим рекомендациям:

• Пишите для людей, а не для машин. Избегайте сухих технических описаний. Объясняйте, зачем нужна функция и как её использовать.
• Документируйте публичный API. Внутренние (private) функции можно не документировать, если их назначение очевидно из кода.
• Используйте примеры. Тег @sample позволяет вставить фрагмент кода из отдельного файла. Это особенно полезно для сложных функций.
• Описывайте null-поведение. В Kotlin важно указывать, может ли параметр или возвращаемое значение быть null.
• Обновляйте документацию. При изменении кода синхронизируйте документацию. Устаревшая документация вреднее её отсутствия.

Пример документирования функции-расширения

Функции-расширения — одна из сильных сторон Kotlin. Документируйте их с помощью тега @receiver:

/**
 * Проверяет, является ли строка валидным email-адресом.
 *
 * @receiver String строка для проверки
 * @return true, если строка соответствует формату email, иначе false
 */
fun String.isValidEmail(): Boolean {
    return this.matches(Regex("^[A-Za-z0-9+_.-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$"))
}

Интеграция документации в CI/CD процесс

Автоматизация генерации документации — залог её актуальности. Добавьте задачу Dokka в ваш CI пайплайн (GitHub Actions, GitLab CI и т.д.). Пример для GitHub Actions:

name: Generate Documentation
on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ub