Schreiben von Dokumentation für Kotlin-Projekte: von A bis Z

Online Python-Trainer für Anfänger

Lernen Sie Python einfach ohne theoretische Überlastung. Lösen Sie praktische Aufgaben mit automatischer Überprüfung und schreiben Sie Code direkt im Browser.

Kurs starten

Einleitung: Warum ist Dokumentation der Schlüssel zum Erfolg eines Kotlin-Projekts?

In der Welt der modernen Kotlin-Entwicklung ist das Schreiben von sauberem und effizientem Code nur die halbe Miete. Die zweite, ebenso wichtige Hälfte ist die Erstellung einer qualitativ hochwertigen Dokumentation. Ein gut dokumentiertes Projekt ist nicht nur eine Ansammlung von Kommentaren. Es ist eine Investition in die Zukunft: Es vereinfacht das Onboarding neuer Entwickler, beschleunigt das Debugging, erleichtert die Wartung der Codebasis und macht Ihre API für andere verständlich. Ohne Dokumentation riskiert selbst der genialste Code, zu einer "Black Box" zu werden, die niemand anfassen möchte.

In diesem Artikel werden wir den gesamten Prozess des Schreibens von Dokumentation für Kotlin-Projekte durchgehen – von den Grundlagen der KDoc-Syntax bis zur automatischen Generierung schöner Websites mit Dokka. Sie erfahren, wie Sie Dokumentation nicht nur nützlich, sondern auch lesbar machen, und lernen Best Practices kennen, die Ihnen helfen, sie aktuell zu halten.

1. Grundlagen von KDoc: Wie man Kommentare in Kotlin schreibt

KDoc ist die standardmäßige Auszeichnungssprache für die Dokumentation von Kotlin-Code, die JavaDoc in vielerlei Hinsicht ähnelt. KDoc-Kommentare beginnen mit /** und enden mit */. Im Inneren wird eine spezielle Auszeichnung verwendet, die es ermöglicht, Parameter, Rückgabewerte und Ausnahmen zu beschreiben.

1.1. Grundlegende Struktur eines KDoc-Kommentars

Die wichtigsten Tags, die Sie am häufigsten verwenden werden:

@param — beschreibt einen Parameter einer Funktion oder Klasse.
@return — beschreibt den Rückgabewert.
@throws oder @exception — beschreibt Ausnahmen, die eine Funktion auslösen kann.
@see — Verweis auf ein anderes Code-Element.
@sample — Verweis auf ein Anwendungsbeispiel.

1.2. Beispiel für eine Funktion

Betrachten wir eine einfache Funktion, die den arithmetischen Mittelwert berechnet:

/** * Berechnet den arithmetischen Mittelwert zweier Zahlen. * * Diese Funktion nimmt zwei ganze Zahlen entgegen und gibt ihren Mittelwert * als Gleitkommazahl zurück. Wenn beide Zahlen Null sind, gibt die Funktion * 0.0 zurück. * * @param a Die erste ganze Zahl. * @param b Die zweite ganze Zahl. * @return Der arithmetische Mittelwert der Zahlen a und b. * @throws IllegalArgumentException wenn beide Parameter Null sind (optional, für das Beispiel). * @see Math#sqrt * @sample com.example.calculator.averageSample */fun average(a: Int, b: Int): Double {    if (a == 0 && b == 0) {        throw IllegalArgumentException("Beide Zahlen dürfen nicht Null sein")    }    return (a + b) / 2.0}

1.3. Dokumentieren von Klassen und Eigenschaften

Nicht nur Funktionen, sondern auch Klassen, Schnittstellen und deren Eigenschaften sollten dokumentiert werden. Dies hilft, den Zweck eines Moduls schnell zu verstehen.

/** * Repository für die Arbeit mit Benutzern. * * Diese Klasse kapselt die Logik für den Zugriff auf Benutzerdaten, * einschließlich Such-, Speicher- und Löschvorgängen. * * @property databaseSource Die Datenquelle für die Datenbank. * @property cacheSource Die Datenquelle für den Cache. * @constructor Erstellt eine Instanz des Repositorys mit den angegebenen Datenquellen. */class UserRepository(    private val databaseSource: UserDatabaseSource,    private val cacheSource: UserCacheSource) {    /**     * Die ID des aktuellen Benutzers.     * Kann null sein, wenn der Benutzer nicht angemeldet ist.     */    var currentUserId: String? = null}

2. Generierungswerkzeuge: Dokka und KDoc

Kommentare manuell zu schreiben ist nur die halbe Arbeit. Um sie in eine benutzerfreundliche Dokumentation (z. B. eine HTML-Website oder ein PDF) umzuwandeln, wird ein Generierungswerkzeug benötigt. Für Kotlin ist der Standard Dokka – eine leistungsstarke Engine, die von JetBrains entwickelt wurde.