Jaké mechanismy existují pro dokumentaci kódu v…

V Kotlinu se pro dokumentaci kódu používá KDoc, který je založen na syntaxi JavaDoc.

Hlavní prvky KDoc:

Bloky dokumentace: Začínají /** a končí */. Nacházejí se před třídou, funkcí, vlastností nebo jinou entitou, kterou je třeba popsat.
Popis: První řádek v bloku dokumentace je stručný popis. Po prázdném řádku může následovat podrobnější popis.
Tagy: Používají se k poskytování strukturovaných informací. Některé běžné tagy:
- @param <název parametru> <popis>: Popisuje parametr funkce nebo konstruktoru.
- @return <popis>: Popisuje návratovou hodnotu funkce.
- @constructor <popis>: Popisuje konstruktor třídy.
- @throws <typ výjimky> <popis>: Popisuje výjimku, kterou může být vyvolána.
- @sample <plné jméno funkce>: Poskytuje příklad použití dokumentované entity.
- @author <jméno>: Uvádí autora kódu.
- @since <verze>: Uvádí verzi, ve které byla entita přidána.
- @see <cílové místo>: Odkazuje na jiný související dokumentační prvek.

Příklad použití KDoc:

/**
 * Tato třída představuje uživatele.
 *
 * @property name Jméno uživatele.
 * @property age Věk uživatele.
 */
class User(
    val name: String,
    val age: Int
) {

    /**
     * Pozdraví uživatele.
     *
     * @param greeting Pozdrav.
     * @return Řetězec s pozdravem a jménem uživatele.
     * @throws IllegalArgumentException Pokud je pozdrav prázdný.
     */
    fun greet(greeting: String): String {
        if (greeting.isEmpty()) {
            throw IllegalArgumentException("Greeting cannot be empty")
        }
        return "$greeting, $name!"
    }
}

Generování dokumentace:

Pro generování dokumentace z KDoc lze použít:

Dokka: Oficiální nástroj pro generování dokumentace v Kotlinu. Podporuje různé výstupní formáty (HTML, Markdown, JSON a další) a může generovat dokumentaci pro smíšené projekty (Kotlin, Java, Scala). Integruje se s Gradle a Maven.
Pluginy pro IDE: IntelliJ IDEA a Android Studio mají vestavěnou podporu KDoc a umožňují prohlížet dokumentaci v vyskakovacích oknech a generovat HTML dokumentaci (na základě Dokka).

Další možnosti:

Markdown: Uvnitř bloků KDoc lze používat základní syntaxi Markdown pro formátování textu (tučný, kurzíva, seznamy, odkazy).
Odkazy: Lze vytvářet odkazy na jiné třídy, funkce nebo vlastnosti pomocí syntaxe [<cílové místo>].

KDoc je mocný nástroj, který pomáhá vytvářet čitelnou a udržovatelnou dokumentaci pro Kotlin kód. Pravidelné používání zlepšuje porozumění kódu týmem a usnadňuje jeho další vývoj.

Jaké mechanismy existují pro dokumentaci kódu v Kotlinu?