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

Введение: Почему документация Kotlin требует особого подхода

Kotlin, будучи современным мультипарадигмальным языком, предлагает разработчикам уникальные возможности: null-безопасность, функции-расширения, корутины и DSL. Однако эти же возможности создают вызовы при документировании. Обычные комментарии в стиле JavaDoc часто не способны адекватно описать сложные конструкции Kotlin. На продвинутом уровне недостаточно просто написать "описание функции". Необходимо создавать документацию, которая будет полезна как для внутренних команд, так и для внешних пользователей библиотек.

В этой статье мы рассмотрим профессиональные инструменты и методики для написания документации Kotlin проектов: от использования KDoc с расширенными тегами до настройки Dokka и интеграции автоматической генерации сайтов.

1. KDoc: Расширенные возможности и теги

KDoc — это стандартный язык разметки для Kotlin, основанный на JavaDoc, но с расширениями под специфику языка. Продвинутые разработчики знают, что KDoc поддерживает Markdown внутри комментариев, что делает его мощнее JavaDoc.

1.1. Основные теги KDoc

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

1.2. Пример продвинутого использования KDoc

Рассмотрим пример функции-расширения с корутинами и null-безопасностью:

/**
 * Асинхронно преобразует список [items] с помощью заданной [transform] функции.
 *
 * Эта функция использует корутины для параллельной обработки элементов.
 * В отличие от стандартного [map], она выполняет преобразования конкурентно.
 *
 * @param T тип элементов исходного списка.
 * @param R тип элементов результирующего списка.
 * @param items список элементов для преобразования.
 * @param transform приостанавливающая (suspend) функция, применяемая к каждому элементу.
 * @return список преобразованных элементов.
 * @throws CancellationException если корутина была отменена во время выполнения.
 * @sample com.example.ParallelMapExample.main
 * @receiver не применяется (функция верхнего уровня).
 */
suspend fun <T, R> parallelMap(
    items: List<T>,
    transform: suspend (T) -> R
): List<R> {
    return coroutineScope {
        items.map { async { transform(it) } }.awaitAll()
    }
}

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

1.3. Документирование DSL

Для DSL (Domain-Specific Languages) в Kotlin особенно важно документировать контекст. Используйте тег @receiver для указания, какой объект является получателем в лямбде:

/**
 * Создает HTML-таблицу.
 *
 * @param init лямбда-инициализатор в контексте [TableBuilder].
 * @receiver [TableBuilder] — объект, предоставляющий методы для настройки таблицы.
 */
fun htmlTable(init: TableBuilder.() -> Unit): String {
    val builder = TableBuilder()
    builder.init()
    return builder.render()
}

2. Dokka: Настройка генерации документации под ваш проект

Dokka — это официальный инструмент для генерации документации из KDoc. На продвинутом уровне важно настроить его под конкретные нужды: многомодульные проекты, интеграция с внешними библиотеками и кастомизация внешнего вида.

2.1. Базовая настройка Gradle

Подключите плагин Dokka в build.gradle.kts:

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

dokka {
    moduleName.set("MyKotlinLib")
    outputDir.set(buildDir.resolve("dokka"))
    dokkaSourceSets {
        named("main") {
            includes.from("README.md") // Включить README как введение
            sourceLink {
                localDirectory.set(file("src/main/kotlin"))
                remoteUrl.set(uri("https://github.com/user/repo/tree/main/src/main/kotlin"))
                remoteLineSuffix.set("#L")
            }
        }
    }
}

2.2. Многомодульные проекты

Для проектов с несколькими модулями (например, core, api, impl) Dokka позволяет объединить документацию в один сайт. Используйте задачу dokkaHtmlMultiModule:

tasks.named<DokkaMultiModuleTask>("dokkaHtmlMultiModule") {
    moduleName.set("My Multi-Module Project")
    outputDirectory.set(buildDir.resolve("dokka-multi"))
}

2.3. Интеграция с MkDocs

Для создания полноценного сайта с документацией (с навигацией, поиском, версионированием) используйте плагин dokka-mkdocs. Он генерирует Markdown-файлы, которые затем обрабатываются MkDocs:

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

tasks.named<DokkaTask>("dokkaMkdocs") {
    outputFormat.set("mkdocs")
    outputDirectory.set(buildDir.resolve("mkdocs"))
}

После генерации запустите mkdocs serve для предпросмотра.

3. Автоматизация и CI/CD для документации

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

3.1. GitHub Actions

Пример workflow для генерации и публикации документации на GitHub Pages:

name: Deploy Docs
on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up JDK 17
        uses: actions/setup-java@v4
        with:
          java-version: '17'
      - name: Generate Dokka Docs
        run: ./gradlew dokkaHtml
      - name: Deploy to GitHub Pages
        uses: peaceiris