Übersetzung: Verwendung der Markdown-Syntax in Javadoc-Kommentaren

Verwenden der Markdown-Syntax in Javadoc-Kommentaren

In diesem Beitrag schauen wir uns an, wie Sie Javadoc-Kommentare mit Markdown anstelle der Standard-Javadoc-Syntax schreiben können. Was ist Markdown? Markdown ist eine einfache Auszeichnungssprache, die optional mit dem gleichnamigen Tool in HTML übersetzt werden kann. Markdown wird häufig zum Formatieren von Readme-Dateien, beim Schreiben von Forenbeiträgen und in Texteditoren verwendet, um schnell schöne Textdokumente zu erstellen. (Wikipedia: Markdown ) In Markdown formatierter Text ist sehr einfach zu lesen. Auf Stack Overflow oder GitHub werden verschiedene Markdown-Varianten verwendet, um benutzergenerierte Inhalte zu formatieren.

Installation

Standardmäßig verwendet das Javadoc-Tool Javadoc-Kommentare, um API-Dokumentation als HTML zu generieren. Dieser Prozess kann mithilfe von Doclets neu konfiguriert werden . Doclets sind Java-Programme, die den Inhalt und die Formatierung der Ausgabedatei des Javadoc-Tools festlegen. Markdown-Doclet ersetzt das Standard-Java-Doclet und gibt dem Entwickler somit die Möglichkeit, Markdown-Syntax in seinen Javadoc-Kommentaren zu verwenden. Sie können es mit maven-javadoc-plugin in Maven installieren . maven-javadoc-plugin 2.9 ch.raffael.doclets.pegdown.PegdownDoclet ch.raffael.pegdown-doclet pegdown-doclet 1.1 true

Kommentare in Markdown schreiben

Sie können jetzt die Markdown-Syntax verwenden, um Javadoc-Kommentare zu schreiben: /** * ## Large headline * ### Smaller headline * * This is a comment that contains `code` parts. * * Code blocks: * * ```java * int foo = 42; * System.out.println(foo); * ``` * * Quote blocks: * * > This is a block quote * * lists: * * - first item * - second item * - third item * * This is a text that contains an [external link][link]. * * [link]: http://external-link.com/ * * @param id the user id * @return the user object with the passed `id` or `null` if no user with this `id` is found */ public User findUser(long id) { ... } Nach der Ausführung

mvn javadoc:Javadoc

Das generierte HTML-API-Dokument befindet sich unter

target/site/apidocs.

Das für den obigen Code generierte Dokument sieht folgendermaßen aus: Wie Sie der Abbildung entnehmen können, werden Javadoc-Kommentare perfekt in HTML konvertiert.

Abschluss

Markdown hat einen klaren Vorteil gegenüber der Standard-Javadoc-Syntax: Es ist viel einfacher, Quellcode einzulesen. Schauen Sie sich einfach einige der Methodenkommentare in java.util.Map an: Viele davon sind voller Formatierungs-Tags und ohne den Einsatz zusätzlicher Tools schwer zu lesen. Sie müssen jedoch bedenken, dass Markdown Probleme mit Tools und IDEs verursachen kann, die nur mit der Standard-Javadoc-Syntax funktionieren. Quelle: Verwendung der Markdown-Syntax in Javadoc-Kommentaren von unserem JCG-Partner Michael Scharhag vom mscharhag-Blog Programming and Stuff.