Java-Dokumentationskommentare: Javadoc und Kommentartypen meistern

Die Java-Sprache unterstützt drei Arten von Kommentaren:

Nr.	Kommentar & Beschreibung
1	*/ Text /* – Der Compiler ignoriert alles von /* bis */. (Mehrzeilig)
2	//Text – Der Compiler ignoriert alles von // bis zum Zeilenende. (Einzeilig)
3	/ Dokumentation /* – Dies ist ein Dokumentationskommentar, allgemein Doc Comment genannt. Das JDK javadoc-Tool verwendet Doc Comments für die automatische Dokumentationsgenerierung.

Dieses Kapitel erklärt Javadoc. Wir sehen, wie wir Javadoc nutzen können, um nützliche HTML-Dokumentation aus Java-Quellcode zu generieren.

Was ist Javadoc?

Javadoc ist ein Tool, das mit dem JDK geliefert wird und Java-Code-Dokumentation im HTML-Format aus Java-Quellcode generiert, der Dokumentation in einem vordefinierten Format erfordert.

Beispiel

/**
 * Das HalloWelt-Programm implementiert eine Anwendung, die
 * einfach "Hallo Welt!" auf der Standardausgabe anzeigt.
 *
 * @author Max Mustermann
 * @version 1.0
 * @since 2024-01-15
 */
public class HalloWelt {
    public static void main(String[] args) {
        // Gibt Hallo, Welt! auf Standardausgabe aus.
        System.out.println("Hallo Welt!");
    }
}

Sie können HTML-Tags innerhalb der Beschreibung verwenden. Zum Beispiel <h1>...</h1> für Überschriften und <p> für Absatzumbrüche:

Beispiel mit HTML

/**
 * <h1>Hallo, Welt!</h1>
 * Das HalloWelt-Programm implementiert eine Anwendung, die
 * einfach "Hallo Welt!" auf der Standardausgabe anzeigt.
 * <p>
 * Gute Kommentare machen Ihr Programm benutzerfreundlicher
 * und gelten als hochwertiger Code.
 *
 * @author Max Mustermann
 * @version 1.0
 * @since 2024-01-15
 */
public class HalloWelt {
    public static void main(String[] args) {
        System.out.println("Hallo Welt!");
    }
}

Die Javadoc-Tags

Das javadoc-Tool erkennt folgende Tags:

Tag	Beschreibung	Syntax
@author	Fügt den Autor einer Klasse hinzu.	@author Name-Text
{@code}	Zeigt Text in Code-Schrift an, ohne HTML/Javadoc-Tags zu interpretieren.	{@code Text}
{@docRoot}	Relativer Pfad zum Wurzelverzeichnis der generierten Dokumentation.	{@docRoot}
@deprecated	Markiert API als veraltet.	@deprecated Beschreibung
@exception	Fügt „Throws“-Unterabschnitt hinzu (Synonym zu @throws).	@exception Klassenname Beschreibung
{@inheritDoc}	Erbt Kommentar von der nächsten vererbbaren Klasse/Interface.	{@inheritDoc}
{@link}	Fügt Inline-Link mit sichtbarer Beschriftung ein.	{@link package.Klasse#Mitglied Beschriftung}
{@linkplain}	Wie {@link}, aber Beschriftung in Normaltext.	{@linkplain package.Klasse#Mitglied Beschriftung}
@param	Fügt Parameter zur „Parameter“-Sektion hinzu.	@param parameter-name Beschreibung
@return	Fügt „Returns“-Sektion mit Beschreibung hinzu.	@return Beschreibung
@see	Fügt „See Also“-Überschrift mit Link/Text hinzu.	@see Referenz
@serial	Für serialisierbare Felder.	@serial Feldbeschreibung \| include \| exclude
@serialData	Dokumentiert Daten von writeObject/writeExternal.	@serialData Datenbeschreibung
@serialField	Dokumentiert ObjectStreamField-Komponente.	@serialField Feldname Feldtyp Feldbeschreibung
@since	Fügt „Since“-Überschrift mit Version hinzu.	@since Release
@throws	Synonym zu @exception.	@throws Klassenname Beschreibung
{@value}	Zeigt Wert einer statischen Konstante an.	{@value package.Klasse#feld}
@version	Fügt „Version“-Unterabschnitt hinzu (mit -version Option).	@version Versions-Text

Vollständiges Beispiel

Das folgende Programm verwendet wichtige Tags. Die Dokumentation wird in AddNum.html und ein Master-File index.html erstellt.

import java.io.*;

/**
 * <h1>Zwei Zahlen addieren!</h1>
 * Das AddNum-Programm addiert zwei ganze Zahlen und gibt
 * das Ergebnis auf dem Bildschirm aus.
 * <p>
 * <b>Hinweis:</b> Gute Kommentare machen Programme benutzerfreundlicher
 * und gelten als hochwertiger Code.
 *
 * @author Max Mustermann
 * @version 1.0
 * @since 2024-01-15
 */
public class AddNum {

    /**
     * Addiert zwei Ganzzahlen. Einfaches Beispiel für Javadoc-Tags.
     * @param numA Erster Parameter für addNum
     * @param numB Zweiter Parameter für addNum
     * @return int Summe von numA und numB
     */
    public int addNum(int numA, int numB) {
        return numA + numB;
    }

    /**
     * Hauptmethode, die addNum verwendet.
     * @param args Unbenutzt.
     * @return Nichts.
     * @exception IOException Bei Eingabefehler.
     * @see IOException
     */
    public static void main(String args[]) throws IOException {
        AddNum obj = new AddNum();
        int sum = obj.addNum(10, 20);
        System.out.println("Summe von 10 und 20 ist: " + sum);
    }
}

Javadoc ausführen

$ javadoc AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Standard Doclet version 17.0.x
Building tree for all packages and classes...
Generating AddNum.html...
Generating package-frame.html...
Generating package-summary.html...
Generating package-tree.html...
Generating constant-values.html...
Building index for all packages and classes...
Generating overview-tree.html...
Generating index-all.html...
Generating deprecated-list.html...
Building index for all classes...
Generating allclasses-frame.html...
Generating allclasses-noframe.html...
Generating index.html...
Generating help-doc.html...

Die generierte Dokumentation können Sie unter AddNum.html einsehen. Für JDK 1.7 wird empfohlen, das Standard-Stylesheet von Oracle zu verwenden.

Java Applets erklärt: Grundlagen & wichtige Unterschiede Java 10: Neue Features, Release-Modell & OpenJDK-Fokus im Überblick

Java