Документирование кода Kotlin

Язык, используемый для документирования кода 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 <name>

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

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

@return

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

@constructor

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

@receiver

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

@property <name>

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

@throws <class>, @exception <class>

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

@sample <identifier>

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

@see <identifier>

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

@author

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

@since

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

@suppress

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

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

Инлайновая разметка

Для инлайновой разметки 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.