Документация кода Kotlin: KDoc и Dokka

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

Генерация документации

Инструмент генерации документации для Kotlin называется Dokka. Инструкции по использованию см. в README Dokka.

Dokka имеет плагины для Gradle, Maven и Ant, позволяющие интегрировать генерацию документации в ваш процесс сборки.

Синтаксис 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 имя

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

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

@return

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

@constructor

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

@receiver

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

@property имя

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

@throws класс, @exception класс

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

@sample идентификатор

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

@see идентификатор

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

@author

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

@since

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

@suppress

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

Инлайновое форматирование

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

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

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

Use the method [foo] for this purpose.

Если вы хотите указать пользовательское обозначение для ссылки, используйте Markdown синтаксис со ссылкой:

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

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

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

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

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

Документация модуля и пакета

Документация модуля в целом, а также пакетов в этом модуле предоставляется в отдельном файле Markdown, а пути к этому файлу передаются Dokka с помощью параметра -include командной строки или соответствующих параметров в плагинах Ant, Maven и Gradle.

Внутри файла документация модуля в целом и отдельных пакетов вводятся соответствующими заголовками первого уровня. Текст заголовка должен быть Модуль <module name> для модуля и Пакет <package qualified name> для пакета.

Вот пример содержимого файла:

# Module kotlin-demo

The module shows the Dokka syntax usage.

# Package org.jetbrains.kotlin.demo

Contains assorted useful stuff.

## Level 2 heading

Text after this heading is also part of documentation for `org.jetbrains.kotlin.demo`

# Package org.jetbrains.kotlin.demo2

Useful stuff in another package.

Последнее изменение: 07 апреля 2022 г.

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