Документация кода 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 имя

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

@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.

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

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.

Последнее изменение: 29 марта 2023 г.

© 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