Документирование кода Kotlin: KDoc

Язык, используемый для документирования кода Kotlin (аналог Javadoc для Java), называется KDoc. По сути, KDoc сочетает синтаксис Javadoc для блочных тегов (расширенный для поддержки специфичных для Kotlin конструкций) и Markdown для встроенной разметки.

Синтаксис KDoc

Как и в Javadoc, комментарии KDoc начинаются с /** и заканчиваются */. Каждая строка комментария может начинаться со звёздочки, которая не считается частью содержимого комментария.

По соглашению первый абзац текста документации (блок текста до первой пустой строки) содержит краткое описание элемента, а следующий за ним текст — подробное описание.

Каждый блочный тег начинается с новой строки и символа @.

Вот пример класса, документированного с помощью KDoc:

/**
 * A group of *members*.
 *
 * This class has no useful logic; it's just a documentation example.
 *
 * @param T the type of a member in this group.
 * @property name the name of this group.
 * @constructor Creates an empty group.
 */
class Group<T>(val name: String) {
    /**
     * Adds a [member] to this group.
     * @return the new size of the group.
     */
    fun add(member: T): Int { ... }
}

Блочные теги

В настоящее время KDoc поддерживает следующие блочные теги:

@param name

Документирует параметр-значение функции или параметр типа класса, свойства либо функции. Чтобы лучше отделить имя параметра от описания, при желании можно заключить имя параметра в квадратные скобки. Поэтому следующие два варианта записи эквивалентны:

@param name description.
@param[name] description.

@return

Документирует возвращаемое функцией значение.

@constructor

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

@receiver

Документирует получатель функции-расширения.

@property name

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

@throws class, @exception class

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

@sample identifier

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

@see identifier

Добавляет ссылку на указанный класс или метод в раздел документации См. также.

@author

Указывает автора документируемого элемента.

@since

Указывает версию программного обеспечения, в которой был добавлен документируемый элемент.

@suppress

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

Встроенная разметка

Для встроенной разметки KDoc использует обычный синтаксис Markdown, расширенный поддержкой сокращённого синтаксиса для ссылок на другие элементы кода.

Ссылки на элементы

Чтобы создать ссылку на другой элемент (класс, метод, свойство или параметр), просто заключите его имя в квадратные скобки:

Use the method [foo] for this purpose.

Если вы хотите указать для ссылки собственную подпись, добавьте её в ещё одну пару квадратных скобок перед ссылкой на элемент:

Use [this method][foo] for this purpose.

В ссылках на элементы также можно использовать полные имена. Обратите внимание: в отличие от Javadoc, в полных именах для разделения компонентов всегда используется точка, в том числе перед именем метода:

Use [kotlin.reflect.KClass.properties] to enumerate the properties of the class.

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

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

Внешние ссылки

Чтобы добавить внешнюю ссылку, используйте стандартный синтаксис Markdown:

For more information about KDoc syntax, see [KDoc](<example-URL>).

Что дальше?

Узнайте, как пользоваться инструментом генерации документации Kotlin: Dokka.

12 августа 2026

© 2010–2026 JetBrains s.r.o. and Kotlin Programming Language contributors
Licensed under the Apache License, Version 2.0.
https://kotlinlang.org/docs/kotlin-doc.html