Документация 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 класс, @исключение класс
Документирует исключение, которое может быть выброшено методом. Поскольку 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.
© 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
