1. Was ist Dokka und warum braucht man es?

Dokka ist eine moderne Engine zur Generierung von Dokumentation für die Programmiersprache Kotlin, entwickelt von JetBrains. Im Gegensatz zum traditionellen JavaDoc versteht Dokka die Besonderheiten von Kotlin: Null-Sicherheit, Erweiterungsfunktionen, Properties, Coroutinen, Sealed-Klassen und andere einzigartige Sprachkonstrukte. Wenn Sie eine Bibliothek oder API in Kotlin schreiben, ermöglicht Ihnen Dokka, automatisch eine lesbare, strukturierte Dokumentation in den Formaten HTML, Markdown, Javadoc oder sogar als JSON zur weiteren Verarbeitung zu erstellen.

Warum ist es wichtig? Erstens vereinfacht Dokka die Wartung der Dokumentation in großen Projekten erheblich – schreiben Sie einfach KDoc-Kommentare (das Pendant zu JavaDoc, aber mit Markdown-Unterstützung) in Ihren Code, und das Tool generiert eine fertige Website. Zweitens kann Dokka die Dokumentation aus mehreren Gradle- oder Maven-Modulen in einem einzigen Projekt zusammenführen, was für Multi-Modul-Bibliotheken entscheidend ist. Drittens unterstützt es die Anpassung über Vorlagen und Plugins, sodass Sie das Erscheinungsbild an Ihren Corporate Style anpassen können.

Dokka wird aktiv in der offiziellen Kotlin-Dokumentation (kotlinlang.org), in den Bibliotheken Ktor, Exposed, Kotlinx.serialization und vielen anderen eingesetzt. Es ist der De-facto-Standard für die Dokumentation von Kotlin-Projekten. Wenn Ihre Bibliothek professionell aussehen soll, ist Dokka ein Muss.

2. Installation

Dokka wird als Plugin für die Build-Systeme Gradle und Maven vertrieben. Es gibt keinen separaten pip- oder npm-Befehl, da es sich um ein Tool für die JVM-Ökosystem handelt. Nachfolgend finden Sie die genauen Anweisungen für Gradle (Kotlin DSL) – die gängigste Methode.

Gradle (Kotlin DSL) – Plugin für ein einzelnes Modul

Fügen Sie Folgendes in Ihre build.gradle.kts ein:

plugins {
    id("org.jetbrains.dokka") version "1.9.20"
}

dependencies {
    // Ihre Abhängigkeiten
}

// Basis-Konfiguration (optional)
tasks.withType<org.jetbrains.dokka.gradle.DokkaTask>() {
    outputDirectory.set(file("$buildDir/dokka"))
}

Gradle (Groovy DSL)

plugins {
    id "org.jetbrains.dokka" version "1.9.20"
}

Maven

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <version>1.9.20</version>
    <executions>
        <execution>
            <phase>pre-site</phase>
            <goals>
                <goal>dokka</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Nach der Konfiguration führen Sie den folgenden Befehl aus:

./gradlew dokkaHtml       # für HTML
./gradlew dokkaGfm        # für Markdown (GFM)
./gradlew dokkaJavadoc    # für Javadoc-Stil

3. Schnellstart – Minimales Arbeitsbeispiel

Erstellen Sie eine einfache Kotlin-Datei mit KDoc-Kommentaren:

// src/main/kotlin/com/example/Calculator.kt
package com.example

/**
 * Ein einfacher Taschenrechner zur Demonstration von Dokka.
 *
 * @author PythonLib Team
 * @since 1.0.0
 */
class Calculator {

    /**
     * Addiert zwei Zahlen.
     *
     * @param a erster Summand
     * @param b zweiter Summand
     * @return Summe von a und b
     */
    fun add(a: Int, b: Int): Int = a + b

    /**
     * Teilt eine Zahl durch eine andere.
     *
     * @param a Dividend
     * @param b Divisor (darf nicht Null sein)
     * @return Ergebnis der Division
     * @throws IllegalArgumentException wenn b == 0
     */
    fun divide(a: Double, b: Double): Double {
        require(b != 0.0) { "Der Divisor darf nicht Null sein" }
        return a / b
    }
}

Führen Sie ./gradlew dokkaHtml aus. Im Ordner build/dokka finden Sie die generierte HTML-Dokumentation.