питон либ луна питонлиб солнце progerlib цветок

Изменить тему

Вход Регистрация

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

Онлайн-тренажер Python для начинающих

Изучайте Python легко и без перегрузки теорией. Решайте практические задачи с автоматической проверкой, получайте подсказки на русском языке и пишите код прямо в браузере — без необходимости что-либо устанавливать.

Начать курс

Введение: Почему документация — ключ к успеху Kotlin проекта?

В мире современной разработки на Kotlin написание чистого и эффективного кода — лишь половина дела. Вторая, не менее важная часть — это создание качественной документации. Хорошо документированный проект — это не просто набор комментариев. Это инвестиция в будущее: он упрощает онбординг новых разработчиков, ускоряет отладку, облегчает поддержку кодовой базы и делает ваш API понятным для других. Без документации даже самый гениальный код рискует превратиться в "чёрный ящик", который никто не хочет трогать.

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

1. Основы KDoc: Как писать комментарии в Kotlin

KDoc — это стандартный язык разметки для документирования кода на Kotlin, во многом похожий на JavaDoc. Комментарии KDoc начинаются с /** и заканчиваются */. Внутри используется специальная разметка, позволяющая описывать параметры, возвращаемые значения и исключения.

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

Основные теги, которые вы будете использовать чаще всего:

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

1.2. Пример для функции

Рассмотрим простую функцию, которая вычисляет среднее арифметическое:

/**
 * Вычисляет среднее арифметическое двух чисел.
 *
 * Эта функция принимает два целых числа и возвращает их среднее значение
 * в виде числа с плавающей точкой. Если оба числа равны нулю, функция
 * вернёт 0.0.
 *
 * @param a Первое целое число.
 * @param b Второе целое число.
 * @return Среднее арифметическое чисел a и b.
 * @throws IllegalArgumentException если оба параметра равны нулю (необязательно, для примера).
 * @see Math#sqrt
 * @sample com.example.calculator.averageSample
 */
fun average(a: Int, b: Int): Double {
    if (a == 0 && b == 0) {
        throw IllegalArgumentException("Оба числа не могут быть нулями")
    }
    return (a + b) / 2.0
}

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

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

/**
 * Репозиторий для работы с пользователями.
 *
 * Этот класс инкапсулирует логику доступа к данным пользователей,
 * включая операции поиска, сохранения и удаления.
 *
 * @property databaseSource Источник данных для базы данных.
 * @property cacheSource Источник данных для кэша.
 * @constructor Создаёт экземпляр репозитория с заданными источниками данных.
 */
class UserRepository(
    private val databaseSource: UserDatabaseSource,
    private val cacheSource: UserCacheSource
) {
    /**
     * Идентификатор текущего пользователя.
     * Может быть null, если пользователь не авторизован.
     */
    var currentUserId: String? = null
}

2. Инструменты генерации: Dokka и KDoc

Писать комментарии вручную — это полдела. Чтобы превратить их в удобную документацию (например, в HTML-сайт или PDF), нужен инструмент генерации. Для Kotlin стандартом является Dokka — мощный движок, разработанный JetBrains.

2.1. Что такое Dokka?

Dokka — это генератор документации, который понимает KDoc и может создавать документацию в различных форматах:

  • HTML — самый популярный формат для веб-сайтов.
  • Markdown — для использования в Git-репозиториях (например, в папке docs).
  • Javadoc — для совместимости с Java-проектами.
  • PDF — для печатных версий.

2.2. Настройка Dokka в Gradle (Kotlin DSL)

Добавьте плагин в файл build.gradle.kts:

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

dokka {
    moduleName.set("Мой Kotlin Проект")
    outputDirectory.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/username/repo/tree/main/src/main/kotlin"))
                remoteLineSuffix.set("#L")
            }
        }
    }
}

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

2.3. Использование @sample для живых примеров

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

/**
 * Вычисляет факториал числа.
 *
 * @sample com.example.samples.factorialSample
 */
fun factorial(n: Int): Long {
    return if (n == 0) 1L else n * factorial(n - 1)
}

Файл с примерами (например, src/test/kotlin/com/example/samples.kt):

// sampleStart
fun factorialSample() {
    val result = factorial(5)
    println(result) // Выведет 120
}
// sampleEnd

3. Лучшие практики: Как писать документацию, которую будут читать

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

3.1. Пишите для людей, а не для машин

Избегайте сухих фраз вроде "Возвращает значение". Вместо этого объясните зачем нужна функция. Сравните: