Connect with us

Программирование

Документируем код 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, он может создавать для нас лучшую визуальную документацию.

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

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

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

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

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

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

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

Источник

Если вы нашли опечатку - выделите ее и нажмите Ctrl + Enter! Для связи с нами вы можете использовать info@apptractor.ru.
Advertisement

Популярное

Спасибо!

Теперь редакторы в курсе.