Dokka für Kotlin: Das komplette Tutorial mit Praxisbeispielen

Einführung in Dokka: Was ist das und warum braucht man es?

Dokka ist ein leistungsstarkes Tool zur Generierung von Dokumentation aus Kotlin-Quellcode. Entwickelt von JetBrains, ist Dokka die offizielle Lösung für die Erstellung von Dokumentation für Kotlin-Projekte. Es analysiert Ihren Code, extrahiert KDoc-Kommentare (das Äquivalent zu JavaDoc für Kotlin) und generiert strukturierte Dokumentation in verschiedenen Formaten: HTML, Markdown, Javadoc und mehr.

Warum Dokka verwenden?

• Automatisierung: Sie müssen Dokumentation nicht manuell schreiben. Dokka generiert sie basierend auf Ihrem Code und Ihren Kommentaren.
• Aktualität: Die Dokumentation ist immer auf dem neuesten Stand des Codes, da sie direkt daraus generiert wird.
• Kotlin Multiplatform Support: Dokka funktioniert hervorragend mit Multiplattform-Projekten und fasst Dokumentation aus verschiedenen Modulen (common, jvm, js, native) zusammen.
• Flexibilität: Sie können das Aussehen, das Ausgabeformat anpassen und bestimmte Code-Teile ein- oder ausschließen.
• Integration: Lässt sich einfach in Gradle- und Maven-Build-Systeme integrieren.

Dokka ist unverzichtbar für Entwickler von Bibliotheken, APIs und großen Projekten, bei denen eine qualitativ hochwertige Dokumentation für die Benutzer entscheidend ist.

Dokka Installation

Dokka wird nicht über pip oder npm installiert, da es ein Tool für das Kotlin/JVM-Ökosystem ist. Die primäre Installationsmethode erfolgt über das Build-System Gradle (empfohlen) oder Maven.

Installation mit Gradle (Kotlin DSL)

// build.gradle.kts
plugins {
    id("org.jetbrains.dokka") version "1.9.20" // Prüfen Sie die aktuelle Version
}

// Oder über apply plugin:
// apply(plugin = "org.jetbrains.dokka")

Installation mit Gradle (Groovy DSL)

// build.gradle
plugins {
    id 'org.jetbrains.dokka' version '1.9.20'
}

Installation mit Maven

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

Schnellstart: Erster Durchlauf

Nachdem Sie das Plugin eingebunden haben, müssen Sie ein paar KDoc-Kommentare in Ihren Code schreiben und die Gradle-Aufgabe ausführen.

Schritt 1: Code mit Kommentaren schreiben

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

/**
 * Ein einfacher Taschenrechner für grundlegende arithmetische Operationen.
 *
 * @author PythonLib Team
 * @since 1.0.0
 */
class Calculator {

    /**
     * Addiert zwei ganze Zahlen.
     *
     * @param a Der erste Summand.
     * @param b Der zweite Summand.
     * @return Die Summe von a und b.
     */
    fun add(a: Int, b: Int): Int = a + b

    /**
     * Teilt eine Zahl durch eine andere.
     *
     * @param dividend Der Dividend.
     * @param divisor Der Divisor. Darf nicht Null sein.
     * @return Das Ergebnis der Division.
     * @throws IllegalArgumentException wenn divisor gleich Null ist.
     */
    fun divide(dividend: Double, divisor: Double): Double {
        if (divisor == 0.0) throw IllegalArgumentException("Divisor darf nicht Null sein")
        return dividend / divisor
    }
}

Schritt 2: Generierung starten

Führen Sie im Terminal folgenden Befehl aus:

./gradlew dokkaHtml

Nach der Ausführung wird die Dokumentation im Ordner build/dokka/html generiert. Öffnen Sie die index.html in Ihrem Browser.

Wichtige Methoden und Funktionen von Dokka (Gradle API)

Dokka bietet eine umfangreiche API zur Anpassung der Dokumentationsgenerierung. Hier sind die wichtigsten Methoden und Konfigurationen, die Sie am häufigsten verwenden werden.

1. dokkaHtml — HTML-Dokumentation generieren