Документация кода 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–2023 JetBrains s.r.o. and Kotlin Programming Language contributors
Licensed under the Apache License, Version 2.0.
https://kotlinlang.org/docs/kotlin-doc.html
