GEDOPLAN
Java SE

Endlich wieder Doku! Javadoc schreiben mit Markdown

Java SE
lighthouse 2225445 640

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 @param und @return kö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?JavadocMarkdownErgebnis
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?JavadocMarkdownErgebnis
Sourcecode{@code int x = 5;}`int x = 5;`int x = 5;
Codeblock<pre>
var x;
var y;
</pre>
```
var x;
var y;
```
  var x;
var y;
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?JavadocMarkdownErgebnis
Ungeordnete Liste (Punkte)<ul>
<li>dies</li>
  <li>das</li>
</ul>
- dies
- das
– dies
– das
Geordnete Liste (Nummerierung)<ol>
<li>hier</li>
<li>da</li>
</ol>
  
1. hier
2. da
1. hier
2. da
Tabelle<table>
  <tr>
    <th>english</th>
    <th>deutsch</th>
  </tr>
<tr>
    <td>one</td>
    <td>eins</td>
  </tr>
  <tr>
    <td>two</td>
    <td>zwei</td>
  </tr>
</table>
| english | deutsch |
|--------|---------|
| one | eins |
| two | zwei |
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!

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert

Bitte füllen Sie dieses Feld aus.
Bitte füllen Sie dieses Feld aus.
Bitte gib eine gültige E-Mail-Adresse ein.
Sie müssen den Bedingungen zustimmen, um fortzufahren.

Autor

Diesen Artikel teilen

LinkedIn
Xing

Gibt es noch Fragen?

Fragen beantworten wir sehr gerne! Schreibe uns einfach per Kontaktformular.

Kurse

weitere Blogbeiträge

IT-Training - GEDOPLAN
Java SE

Checkstyle kann nun auch Java 7!

Mein Flehen wurde erhört: Die Version 5.5 ist verfügbar. Sie kennt auch die neuen Syntaxelemente von Java 7. Dazu passend…
IT-Training - GEDOPLAN
Webprogrammierung

Angular 2 – Lazy Load Modules

Unsere bisherigen Beispiele sind alle davon ausgegangen das es ein zentrales Modul gibt dessen Referenzen von Webpack analysiert und in…
IT-Training - GEDOPLAN
Jakarta EE (Java EE)

Bean Validation auf Collections

Die zum Java-EE-6-Umfang gehörende Spezifikation Bean Validation (JSR 303) stellt einen wesentlichen Schritt zur einheitlichen Validierung von Geschäftsdaten dar. Wie…

Work Life Balance. Jobs bei Gedoplan

We are looking for you!

Lust bei GEDOPLAN mitzuarbeiten? Wir suchen immer Verstärkung – egal ob Entwickler, Dozent, Trainerberater oder für unser IT-Marketing! Schau doch einfach mal auf unsere Jobseiten! Wir freuen uns auf Dich!

Work Life Balance. Jobs bei Gedoplan

We are looking for you!

Lust bei GEDOPLAN mitzuarbeiten? Wir suchen immer Verstärkung – egal ob Entwickler, Dozent, Trainerberater oder für unser IT-Marketing! Schau doch einfach mal auf unsere Jobseiten! Wir freuen uns auf Dich!