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

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

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

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

В 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 <name>

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

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

@return

Описание возвращаемого функцией значения.

@constructor

Описание первичного конструктора класса.

@receiver

Описание расширения функции.

@property <name>

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

@throws <class>, @exception <class>

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

@sample <identifier>

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

@see <identifier>

Добавляет ссылку на спецификацию класса или метода на See Also блок документации.

@author

Определяет автора документируемого элемента.

@since

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

@suppress

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

KDoc не поддерживает @deprecated тег. Вместо него используйте @Deprecated аннотацию. {:.note}

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

Для встроенной разметки 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 <module name>” для модуля, и “Package <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.