JEP 467: Markdown-Dokumentationskommentare

Ziel

Unterstützung der Markdown-Syntax in Java-Dokumentationskommentaren, um die Lesbarkeit zu verbessern und eine prägnantere Dokumentation zu fördern.

Motivation

• Bisheriges JavaDoc ist auf HTML-Tags angewiesen → zu ausführlich und schwer zu lesen.
• Entwickler sind bereits mit Markdown aus README-Dateien, GitHub usw. vertraut.
• Durch Markdown-Unterstützung wird konsistente und knappe Dokumentation möglich.

Beschreibung

• Unterstützung der auf CommonMark basierenden Markdown-Syntax innerhalb von JavaDoc-Kommentaren.
• Bestehende HTML-Kommentare können weiterhin verwendet werden.
• Anstelle der bisherigen Kommentarform /* ... */ wird /// verwendet, um einen Markdown-Dokumentationskommentar zu kennzeichnen.
• JavaDoc-Tools von Drittanbietern übernehmen das Parsen und Rendern von Markdown.

Markdown-Spezifikation

• Basierend auf CommonMark.
• Unterstützte Syntax:
  • Überschriften (#, ##, ### usw.)
  • Listen (geordnet/ungeordnet)
  • Code-Blöcke (```)
  • Links
  • Tabellen (nach GitHub Flavored Markdown)
  • Blockzitate
  • Hervorhebungen (*kursiv*, **fett**)

Java-spezifische Tags

Zusammen mit Markdown können weiterhin bestehende JavaDoc-@-Tags verwendet werden:

• @param
• @return
• @throws
• @see
• @since
• @deprecated

[devnamho0910]

Ausgezeichnet …

[carnoxen]

Scheint also in den Standard aufgenommen worden zu sein.

[click]

Ist in JDK 23 aufgenommen worden.
Ich habe es getestet: Selbst wenn die JDK-Version des Projekts unter 23 liegt, funktioniert es normal, sofern die IDE oder das JavaDoc-Export-Tool es unterstützt.