Программирование
Документируем код Kotlin с KDoc
Когда вы создаете библиотеку и хотите опубликовать ее на GitHub, или просто пишете код для какого-то проекта, вам так или иначе нужно сделать хорошую документацию.
KDoc — язык написания документов для кода Kotlin. Как и в случае с JavaDoc, основным форматом KDoc является:
Начиная с / ** и заканчивая * /.
В KDoc мы можем использовать теги. Формула тега — @tagname + space + name (или иногда просто @tagname), вот пример:
В приведенном выше коде вы можете увидеть:
- Сначала я пишу описание функции foo
- Добавляю ввод @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.
