Kurzfassung
Javadoc-Kommentare können in Markdown verfasst werden, anstatt eine Mischung aus HTML und @-Tags verwenden zu müssen.
Bisher: Lesbarer Code, unverständliche Doku
Mit Java 23 wird der Trend fortgesetzt, die Lesbarkeit und Verständlichkeit von Java-Quelltext zu verbessern. Im letzten Artikel haben wir unbenannte Variablen und Patterns betrachtet. Diesmal hat man sich eines Bereiches angenommen, der bisher eher stiefmütterlich behandelt wurde, und zwar auf beiden Seiten: denen, die Java entwickeln und denen, die mit Java entwickeln: Javadoc-Kommentare.
Javadoc: Schwierigkeiten, Unklarheiten, Herausforderungen
Dokumentationskommentare direkt im Quelltext können bis Java 22 in einer Mischung aus HTML und speziellen Javadoc-Tags erstellt werden. Mit einem Tool javadoc aus dem JDK wird daraus dann Dokumentation in Form von HTML-Seiten erstellt.
Diese Syntax ist umständlich, komplex und schwer lesbar, insbesondere direkt im Quelltext. Selbst einfache Formatierungen wie Listen, Tabellen oder Überschriften erfordern schon verhältnismäßig viel Aufwand und die Entwickler müssen sich dann durch den Markup-Overhead kämpfen. Die eingebetteten Javadoc-Tags wie {@code} oder {@link} haben das Ganze mit ihrem ungewohnten Format zusätzlich verkompliziert. All das hat die oft ohnehin schon nicht allzu große Bereitschaft vieler Entwickler, Javadoc-Kommentare zu schreiben, eher noch weiter verringert. Durch die feste Verdrahtung auf HTML werden obendrein eine einfache Wiederverwendung in anderen Systemen oder eine Konvertierung in moderne Dokumentationsformate zusätzlich erschwert.
Bei Erscheinen von Java im Jahre 1995 erschien HTML durchaus als sinnvolle Lösung, heute gibt es aber bessere Alternativen. Der mit Java 18 eingeführte JEP 413: Code Snippets in Java API Documentation machte die Situation nicht wirklich besser.
Java 23: Dokumentationskommentare mit Markdown
In Java 23 wurde der JEP 467: Markdown Documentation Comments eingeführt. Damit wird es möglich, in Dokumentationskommentaren im Java-Quelltext direkt Markdown zu verwenden. Wir können auf HTML komplett verzichten, ein Großteil der oben beschriebenen Nachteile und Problem fallen komplett weg.
Beispiel
Schauen wir uns die Javadoc der Methode min() aus java.lang.Math an:
/**
* Returns the smaller of two {@code int} values. That is,
* the result is the argument closer to the value of
* {@link Integer#MIN_VALUE}. If the arguments have the same
* value, the result is that same value.
*
* @param a an argument.
* @param b another argument.
* @return the smaller of {@code a} and {@code b}.
*/
Mit der Markdown-Neuerung sieht diese nun so aus:
/// Returns the smaller of two `int` values. That is,
/// the result is the argument closer to the value of
/// [Integer#MIN_VALUE]. If the arguments have the same
/// value, the result is that same value.
///
/// @param a an argument.
/// @param b another argument.
/// @return the smaller of `a` and `b`.
Schon auf den ersten Blick können wir sehen, dass der Markdown-Kommentar kürzer und besser lesbar ist.
Schauen wir genauer auf die farblich hervorgehobenen Unterschiede:
- Bei einem Markdown-Kommentar beginnt jede Zeile mit drei Schrägstrichen
///. - Um einen Text als Quelltext zu formatieren, können wir einfache Backticks verwenden:
`int a`. - Statt eines
<p>für den Beginn eines neuen Absatzes genügt eine einfache Leerzeile. - Das längliche
{@link …}für eine Verlinkung kann durch eckige Klammern[ … ]ersetzt werden. - Javadoc-spezifische Elemente wie
@paramund@returnkönnen unverändert weiterverwendet werden und behalten auch ihre bisherige Bedeutung.
Markdown-Formatierungen
Das verwendete Markdown orientiert sich an der CommonMark-Syntax. Nachfolgend schauen wir uns daraus die wichtigsten Möglichkeiten zur Formatierung und Strukturierung von Javadoc-Kommentaren an.
Text
Fett anzuzeigender Text wird in je zwei Sternchen eingeschlossen, kursiv anzuzeigender in je ein Sternchen. Der Beginn eines neuen Absatzes wird durch eine Leerzeile markiert.
| Was? | Javadoc | Markdown | Ergebnis |
|---|---|---|---|
| Fett | <b>fett</b> | **fett** | fett |
| Kursiv | <i>kursiv</i> | *kursiv* | kursiv |
| Absatz | <p> | Leerzeile |
Codeformatierung
Einzeiliger Code wird in einfache Backticks `…` eingeschlossen, mehrzeilige Codeabschnitte mit jeweils drei Backticks am Anfang und am Ende
```
here be code
```Wie oben bereits gezeigt, kann mit eckigen Klammern auf vielerlei Programmelemente verwiesen werden (Methoden, Klassen…). Dabei kann für Klassen aus java.lang der Paketname entfallen, für alle anderen müssen der vollständige Klassenname und bei Methoden auch die korrekte Signatur angegeben werden.
| Was? | Javadoc | Markdown | Ergebnis |
|---|---|---|---|
| Sourcecode | {@code int x = 5;} | `int x = 5;` | int x = 5; |
| Codeblock | <pre> | ``` | var x; |
| Link | {@link Object#hashCode()}{@link java.util.stream.IntStream #range(int, int)} | [Object#hashCode()] [java.util.stream.IntStream #range(int, int)] | Object#hashCode() java.util.stream.IntStream#range(int, int) |
Listen und Tabellen
Listen und Tabellen lassen sich mit Markdown recht simpel erstellen.
Für ungeordnete Listen genügt eine Aufzählung, bei der jede Zeile mit einem Minuszeichen oder einem Stern beginnt. Sollen die Punkte nummeriert werden, dann wird jeder Zeile eine Zahl mit einem Punkt vorangestellt. Dabei müssen die Zahlen nicht fortlaufend sein; es genügt auch, jede Zeil mit 1. zu beginnen. Die korrekte Nummerierung wird dann automatisch ermittelt.
Am deutlichsten zeigt sich der Unterschied im Textaufwand bei Tabellen. Sind in HTML Unmengen von Tags nötig, um die Struktur der Tabelle anzugeben, genügen im Markup senkrechte Striche zum Trennen der Spalten voneinander sowie Bindestriche nach der ersten Zeile, um den Tabellenkopf zu markieren.
Für Listen und Tabellen sind noch diverse weitere Optionen verfügbar, allerdings würde das den Rahmen dieses Textes sprengen.
| Was? | Javadoc | Markdown | Ergebnis |
|---|---|---|---|
| Ungeordnete Liste (Punkte) | <ul> | - dies | – dies – das |
| Geordnete Liste (Nummerierung) | <ol> | 1. hier | 1. hier 2. da |
| Tabelle | <table> | | english | deutsch | |  |
Letzter Schritt: Dokumentation erstellen
Um aus all den Dokumentationskommentaren eine vollständige Javdoc-Dokumentation zu erstellen, kann grundsätzlich wie bisher das Kommandozeilentool javadoc verwendet werden.
Einfacher ist der Vorgang aber mit einer IDE zu erledigen, z.B. in IntelliJ über den Menüpunkt „Tools“ -> „Generate JavaDoc…“
Auch Build-Werkzeuge bringen eine passende Funktionalität mit, z.B. für Maven das maven-javadoc-plugin oder für Gradle die Javadoc Task.
Was bringt’s?
Der Einsatz von Markdown ist ein großer Fortschritt in der Entwicklung der Programmiersprache Java. Die Lesbarkeit der Kommentare wird deutlich verbessert, sie sind leichter zu verstehen und damit auch besser wartbar.
Die leicht zu erlernende Syntax ermöglicht es, ohne viel Lernaufwand auch komplexere Strukturen (z.B. Tabellen) darstellen zu können.
Die Funktionalität von Javadoc bleibt erhalten, also auch, wer diese neuartige Markdown-Formatierung nicht kennt, kann die relevanten Informationen wie Parameter, Rückgabewerte und geworfene Exceptions ohne großen Aufwand schnell erfassen.
Schreibt Kommentare!
Mit diesem Artikel solltet ihr einen soliden Überblick über die Nutzung von Markdown in Javadoc bekommen haben. Damit seid ihr bestens gerüstet, eure Dokumentationen und Kommentare mit Markdown zu erstellen.
Also: Los geht’s, schreibt wieder Javadoc!
