Programmiersprache: Komplettrenovierung für das Kotlin-Dokumentationstool Dokka

Inhaltsverzeichnis

Im Zuge der Entwicklung der nächsten Kotlin-Version hat JetBrains das Dokumentationstool für die Programmiersprache generalüberholt. Das derzeit als Preview verfügbare Dokka baut auf den frisch erschienen Release Candidate von Kotlin 1.4 und bietet zahlreiche Ergänzungen für die Ausgabe nach HTML und Markdown. Außerdem können Entwicklerinnen und Entwickler eigene Beispiele in die Dokumentation integrieren.

Mehr Dynamik

Bisher hat Dokka statische HTML-Seiten erzeugt. Das aktuelle Release erstellt dagegen dynamische Seiten, die unter anderem einen Navigationsbereich und eine Suchfunktion integrieren. Erstere listet alle Module, Pakete und Typen hierarchisch auf und ermöglicht das Auf- und Einklappen der jeweiligen Kindelemente.

Für Multiplattformprojekte, die Kotlin seit Version 1.2 ermöglicht, zeigt der Kopfbereich Badges zu den einzelnen Plattformen und für die allgemein gültigen Inhalte an. Über einen Klick lassen sich die zugehörigen Inhalte filtern, also für die jeweiligen Compile-Ziele ein- und ausblenden. Für online verfügbaren Code lassen sich Verweise aus der Dokumentation über die sourceLink-Option erstellen.

Markdown und Java(doc)

Für die Ausgabe ins Markdown-Format hat Dokka zwei Varianten an Bord: dokkaJekyll erstellt Markdown Jekyll und dokkaGfm GitHub Flavored Markdown (GFM). Für das Zusammenspiel mit Java bietet Dokka Plug-ins für HTML und die beiden Markdown-Formate an, die eine Ausgabe in einem Format verfasst, das Java-Entwicklerinnen und -Entwickler gewohnt sind.

Unter anderem stellt das Tool für den Zugriff auf Klassen-Properties passende get- und set-Methoden dar. Einen Schritt weiter geht der dokkaJavadoc-Task, mit dem die Ausgabe in demselben Format erscheint wie in einer mit Javadoc erstellten Dokumentation für Java-Code.

Spielwiese und Modulvielfalt

Dokka integriert den Kotlin Playground, der einfache Kotlin-Codeschnipsel im Browser ausführen kann. Wer die Dokumentation über Codebeispiele anreichern möchte, kann diese über samples = listOf(<paths to the files>) einbinden und die anzuzeigenden Methoden über @sample <fully qualified name of your method> spezifizieren. Die jeweils in spitzen Klammern stehenden Inhalte sind dabei durch die Datei- beziehungsweise Methodennamen zu ersetzen.

Für Projekte, die aus mehreren Modulen bestehen, erstellt Dokka standardmäßig eine Dokumentation für jedes einzelne Modul. Über den dokkaHtmlCollector-Task lassen sich alle Module zu einer zentralen Dokumentation zusammenfassen. Mit dokkaHtmlMultimodule erstellt Dokka für jedes Modul eine eigene Dokumentation und zusätzlich eine Übersichtsseite, die auf die Modulbeschreibungen verlinkt und jeweils eine Vorschau bietet.

Dokka ist als Plug-in für die Build-Tools Maven und Gradle verfügbar, steht aber auch als separates Tool für die Kommandozeile bereit. Weitere Details dazu und zu den Neuerungen lassen sich dem Kotlin-Blog entnehmen.

(rme)