Кадом механизмҳо барои ҳуҷҷатгузории код дар Kotlin…

Дар Kotlin барои ҳуҷҷатгузории коди KDoc истифода мешавад, ки асоси синтаксиси JavaDoc-ро дорад.

Элементи асосии KDoc:

Блокҳои ҳуҷҷатгузорӣ: Аз /** оғоз шуда, бо */ ба охир мерасад. Онҳо пеши синфи, функсия, хосият ё дигар унсуре, ки бояд тавсиф шавад, ҷойгир мешаванд.
Тавсиф: Сатрҳои аввалини блоки ҳуҷҷатгузорӣ як тавсифи кӯтоҳ аст. Пас аз сатрхои холӣ метавонад тавсифи муфассалтар пайдо шавад.
Тегҳо: Барои пешниҳоди маълумоти сохторӣ истифода мешаванд. Баъзе тегҳои маъмул:
- @param <номи параметр> <тавсиф>: Тавсиф мекунад параметри функсия ё конструктор.
- @return <тавсиф>: Тавсиф мекунад арзиши баргардонидашудаи функсияро.
- @constructor <тавсиф>: Тавсиф мекунад конструктори синфро.
- @throws <намуди истисно> <тавсиф>: Тавсиф мекунад истисно, ки метавонад барояд.
- @sample <номи пурраи функсия>: Маслиҳат медиҳад истифодаи унсури ҳуҷҷатгузоришуда.
- @author <ном>: Муайян мекунад муаллифи коди.
- @since <версия>: Муайян мекунад версия, ки дар он унсур илова шудааст.
- @see <ҷойи ҳадаф>: Маслиҳат медиҳад ба унсури дигаре, ки алоқаманд аст.

Маслиҳати истифодаи KDoc:

/**
 * Ин синф корбарро муаррифӣ мекунад.
 *
 * @property name Номи корбар.
 * @property age Синни корбар.
 */
class User(
    val name: String,
    val age: Int
) {

    /**
     * Корбарро табрик мекунад.
     *
     * @param greeting Табрик.
     * @return Сатр бо табрик ва номи корбар.
     * @throws IllegalArgumentException Агар табрик холӣ бошад.
     */
    fun greet(greeting: String): String {
        if (greeting.isEmpty()) {
            throw IllegalArgumentException("Greeting cannot be empty")
        }
        return "$greeting, $name!"
    }
}

Генератсияи ҳуҷҷат:

Барои генератсияи ҳуҷҷат аз KDoc метавон истифода бурд:

Dokka: Асбоби расмии барои генератсияи ҳуҷҷат дар Kotlin. Он форматҳои гуногунро (HTML, Markdown, JSON ва ғайра) дастгирӣ мекунад ва метавонад ҳуҷҷатҳоро барои лоиҳаҳои омехта (Kotlin, Java, Scala) тавлид кунад. Бо Gradle ва Maven ҳамкорӣ мекунад.
Плагинҳо барои IDE: IntelliJ IDEA ва Android Studio дастгирии дохилии KDoc доранд ва имкон медиҳанд, ки ҳуҷҷатро дар тирезаҳое, ки пайдо мешаванд, бинед ва ҳуҷҷатро дар формати HTML (барои Dokka) тавлид кунед.

Вариантҳои иловагӣ:

Markdown: Дар дохили блокҳои KDoc метавон синтаксисҳои асосии Markdown-ро барои формат кардани матн истифода бурд (бо калимаи мустаҳкам, курсив, рӯйхатҳо, пайвандҳо).
Пайвандҳо: Мумкин аст, ки пайвандҳо ба синфҳо, функсияҳо ё хосиятҳои дигар созед, бо истифода аз синтаксис [<ҷойи ҳадаф>].

KDoc асбоби қавӣ аст, ки кӯмак мекунад, ки ҳуҷҷатгузории хонданӣ ва нигоҳдоштанӣ барои коди Kotlin эҷод кунед. Истифодаи мунтазами он беҳтар кардани фаҳмиши коди гурӯҳ ва осон кардани рушди минбаъдаи он.

Кадом механизмҳо барои ҳуҷҷатгузории код дар Kotlin вуҷуд доранд?