Как использовать @link и @code в KDoc (Kotlin) для правильного документирования кода?

Правильное использование @link и @code в KDoc

Ваша проблема очень распространена среди новичков в Kotlin. Дело в том, что синтаксис KDoc отличается от JavaDoc, и теги @link и @code требуют специального форматирования с фигурными скобками. Давайте разберемся по порядку.

Как работает @code

Тег @code в KDoc работает только внутри фигурных скобок. Правильный синтаксис: {@code текст}. Без скобок он не будет обработан. Вот исправленный пример:

/**
 * Вычисляет сумму двух чисел.
 * @param a первое число типа {@code Int}.
 * @param b второе число типа {@code Int}.
 * @return результат типа {@code Int}.
 */
fun add(a: Int, b: Int): Int {
    return a + b
}

Теперь слово Int будет отображаться моноширинным шрифтом в документации.

Как работает @link

С @link ситуация аналогичная — нужны фигурные скобки. Но есть важные нюансы:

• Ссылка на класс в том же пакете: {@link Calculator}
• Ссылка на класс из другого пакета: {@link com.example.utils.Calculator}
• Ссылка на метод или свойство: {@link Calculator#calculate} или {@link Calculator#calculate(int, int)}
• Ссылка с кастомным текстом: {@link Calculator Калькулятор} — отобразится как "Калькулятор", но будет ссылкой на класс Calculator

Пример правильного использования:

/**
 * Вычисляет сумму двух чисел, используя {@link Calculator}.
 * Для получения результата вызовите {@link Calculator#compute(int, int)}.
 * 
 * @param a первое число типа {@code Int}
 * @param b второе число типа {@code Int}
 * @return результат типа {@code Int}
 */
fun add(a: Int, b: Int): Int {
    val calc = Calculator()
    return calc.compute(a, b)
}

Альтернативный синтаксис с квадратными скобками

В KDoc также поддерживается Markdown-подобный синтаксис для ссылок:

• [Calculator] — автоматическая ссылка на класс Calculator (работает, если класс видим в контексте)
• [Calculator][com.example.Calculator] — явное указание полного имени
• [текст ссылки][Calculator] — кастомный текст

Этот синтаксис короче и часто удобнее. Пример:

/**
 * Использует [Calculator] для вычислений.
 * Смотрите также [Calculator.compute].
 */

Проверка через Dokka

Чтобы убедиться, что всё работает, сгенерируйте документацию с помощью Dokka. Добавьте в build.gradle.kts:

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

tasks.dokkaHtml {
    outputDirectory.set(buildDir.resolve("dokka"))
}

Затем выполните ./gradlew dokkaHtml и откройте сгенерированные HTML-файлы. Вы увидите, что {@code Int} отображается моноширинным шрифтом, а {@link Calculator} — кликабельной ссылкой.

Полный исправленный пример

/**
 * Вычисляет сумму двух чисел, используя {@link Calculator}.
 * 
 * Пример использования:
 * {@code
 *   val result = add(5, 3)
 *   println(result) // 8
 * }
 * 
 * @param a первое слагаемое типа {@code Int}
 * @param b второе слагаемое типа {@code Int}
 * @return сумма {@code a + b} типа {@code Int}
 */
fun add(a: Int, b: Int): Int {
    return a + b
}

Теперь ваша документация будет выглядеть профессионально и информативно!

/**
 * Вычисляет **сумму** двух чисел.
 * 
 * Пример:
 * ```kotlin
 * val result = add(5, 3)
 * ```
 * 
 * @param a первое число типа `Int`
 * @param b второе число типа `Int`
 */

/**
 * Документация по Kotlin: [Kotlin Docs](https://kotlinlang.org/docs/home.html)
 */