Документируем код Kotlin с KDoc

Когда вы создаете библиотеку и хотите опубликовать ее на GitHub, или просто пишете код для какого-то проекта, вам так или иначе нужно сделать хорошую документацию.

KDoc — язык написания документов для кода Kotlin. Как и в случае с JavaDoc, основным форматом KDoc является:

Начиная с / ** и заканчивая * /.

В KDoc мы можем использовать теги. Формула тега — @tagname + space + name (или иногда просто @tagname), вот пример:

В приведенном выше коде вы можете увидеть:

1. Сначала я пишу описание функции foo
2. Добавляю ввод @param, чтобы другие программисты могли понять, что вводится

Давайте посмотрим на некоторые известные теги.

@param => вы можете задокументировать параметр функции или общий тип класса или…:

Как видите, мы можем использовать T или [T] (когда вы используете [T], вы не можете использовать пробел после @param).

• @propertity => опишите свойства конструктора
• @return => опишите возвращаемые результаты функции
• @constructor => опишите основной конструктор
• @throw + class => задокументируйте, какое исключение произойдет, если что-то пойдет не так
• @see => добавьте ссылку или метод в качестве ссылки
• @sample => покажите пример кода

Вы можете найти больше тегов на сайте Kotlin.

Вот хороший пример:

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

Давайте перейдем к следующему шагу — использованию Dokka.

Dokka — это движок документации для Kotlin, он может создавать для нас лучшую визуальную документацию.

Посмотри на эту картинку:

Давайте посмотрим, как мы должны это использовать. Сначала нам нужно добавить это в Gradle:

classpath(“org.jetbrains.dokka:dokka-gradle-plugin:1.4.30”)

После этого введите это на терминале: gradlew.bat dokkaHtml (./gradlew для Linux/Mac), и после сборки вы сможете найти всю документацию в app\build\dokka.

Вместо dokkaHtml вы можете попробовать dokkaGfm и dokkaJavadoc.

Источник