Die Dokumentation von Methoden, Variablen und Klassen ist Teil der Sprache und wird von Standardwerkzeugen des JDK unterstützt.

Die genauen Spezifikationen zum Dokumentieren von Javaklassen sind im Oracle Dokument "Requirements for Writing Java API Specifications" beschrieben. Nach diesen Richtlinien können auch eigene Javaklassen dokumentiert werden. Oracle bietet hierzu ein recht gutes Tutorial an.

Konzept

• Dokumentation zu Variablen und Methoden werden in den Javaquelldateien als Javakommentar in einem besonderen Format beschrieben
• Das Hilfsprogramm javadoc liest Javaquelldateien und erzeugt html Seiten mit der passenden Dokumentation einer Klasse.

Das Format von Kommentaren für Dokumentation

Das Format für die Dokumentation ist ein Sonderfall des mehrzeiligen Javakommentars. Es sieht wie folgt aus:

/**
  * Hier steht Dokumentationskommentar
  * Hier steht eine weitere Zeile mit Dokumentationskommentar
*/

Javakommentare können mit html formatiert werden.

Zusammenfassung für eine Klasse

Beginnen Sie die Dokumentation einer Klasse mit einer Zusammenfassung ihrer Funktion.

Für die Klasse Ware.java kann das wie folgt aussehen:

    /**
    * Ware dient zum Verwalten von Guetern mit Preisen und Namen in einem Lager.
    * @author  Stefan Schneider
    * @version 1.1
    * @see     Lager
    */
    public class Ware {
     ...
    }

Die Klassendokumentation erlaubt die Verwendung von Kennzeichnungen (englisch "Tags") mit denen man weitere Informationen beisteuern kann. Man kann für Klassen die folgenden Kennzeichnungen "Tags" verwenden:

• @since
• @deprecated
• @serial
• @author
• @version
• {@link}
• {@linkplain}
• {@docRoot}

Dokumentation von Klassenvariablen

Zur Dokumentation von Attributen wird die Dokumentation der Deklaration vorangestellt. Bei der Klasse Ware kann die zum Beispiel wie folgt geschehen:

public class Ware {
...
    /**
     * Der aktuelle Mehrwertsteuersatz 2010.
     * Er liegt zur Zeit bei {@value} .
     *
     * @since 1.0
     */
    public static final double mws = 0.19;
...
}

Bei Klassenvariablen können die folgenden Kennzeichnungen "Tags" verwendet werden:

• @see
• @since
• @deprecated
• @serial
• @serialField
• {@link}
• {@linkplain}
• {@docRoot}
• {@value}

Dokumentation von Konstruktoren und Methoden

Die Dokumentation von Konstruktoren und Methoden wird ebenfalls direkt der Implementierung der entsprechenden Methode als Javakommentar vorangestellt. Hiermit kann man neben der Bedeutung der Methode auch die Eingabe- und Ausgabeparameter dokumentieren. Siehe folgendes Beispiel:

    /**
     * Liefert den Namen einer Ware zurueck.
     * @return    Name der Ware
     */
    public String get_name(){return name;}

    /**
     * Setzen eines neuen Nettopreis
     * @param npr   der neue Nettopreis
     */
    public void set_nettoPreis(int npr) {
    ...
    }

Bei Methoden und Konstruktoren sind die folgenden Tags möglich:

• @see
• @since
• @deprecated
• @param
• @return
• @throws und @exception
• @serialData
• {@link}
• {@linkplain}
• {@inheritDoc}
• {@docRoot}

javadoc: Der Java API Generator

Das JDK Programm javadoc (Oracle Dokumentation) erzeugt aus Javaquelldateien Java API Beschreibungen im html Format.

In seiner einfachsten Form kann man eine Java API Dokumentation mit dem folgenden Kommando erzeugen:

$ javadoc JavaQuelldatei.java ... JavaQuelldatei1.java

Das Kommando javadoc hat zahlreiche Optionen (siehe Oracle Dokumentation) die direkt nach dem Kommando eingefügt werden können. Die wichtigsten sind:

• -author Generierung der Dokumentation unter Berücksichtigung des @author tag
• -d Verzeichnis Generiert die Dokumentation in dem angegeben Verzeichnis
• -help zeigt die online Hilfe
• -private generiert Dokumentation auch für private Attribute
• -sourcepath sourcepathlist Liste der Verzeichnisse in denen nach Quelldateien gesucht wird
• -version Generierung der Dokumentation unter Berücksichtigung des @version tag

Beispiel

Für eine Klasse Ware.java mit allen Komponenten:

/**
 * Dies ist die Dokumentation der Klasse Ware. Ware dient zum Verwalten von Gütern
 * mit Preisen und Namen in einem Lager.
 * @author  Stefan Schneider
 * @version 1.1
 * @see     Lager
 */
public class Ware {

    /**
     * Der aktuelle Mehrwertsteuersatz 2010.
     * Er liegt zur Zeit bei {@value}.
     *
     * @since 1.0
     */
    public static final double mws = 0.19;
    private double nettoPreis; //Deklaration
    public boolean halbeMws;
    private String name;

    /**
     * Konstruktor fuer die Klasse Ware
     * @param n der Name der Ware
     * @param np der Nettopreis
     * @param hmws halber Mehrwertsteuersatz für Ware gueltig
     */
    public Ware(String n, double np, boolean hmws) {
        name = n;
        nettoPreis = np;
        halbeMws = hmws;
    }

    /**
     * Liefert den Namen einer Ware zurueck.
     * @return    Name der Ware
     */
    public String get_name() {
        return name;
    }

    /**
     * Setzen eines neuen Nettopreis
     * @param npr  der neue Nettopreis
     * @see "Der kleine Kaufmann. BWL für Einzelhändler"
     */
    public void set_nettoPreis(double npr) {
        nettoPreis = npr;
    }

    /**
     * Ausdrucken aller Werte auf der Konsole
     */
    public void drucken() {
        System.out.println("Name: " + name);
        System.out.println("netto: " + nettoPreis);
        System.out.println("Brutto: " + bruttoPreis());
        System.out.println("Halbe Mws:" + halbeMws);
    }

    /**
     * Ausgabe des Nettopreis
     * @return der Nettopreis

     */
    public double nettoPreis() {
        return nettoPreis;
    }

    /**
     * Ausgabe des Bruttopreis
     * @return der Bruttopreis
     */
    public double bruttoPreis() {
        double bp; //temporaere Variable; keine Klassenvariable
        if (halbeMws) {
            bp = Math.round(nettoPreis * (mws / 2 + 1) * 100) / 100;
        } else {
            bp = Math.round(nettoPreis * (mws + 1) * 100) / 100;
        }
        return bp;
    }
}

Die Dokumentation kann mit dem Kommando javadoc generiert werden. Für das oben gezeigte Beispiel werden zwei Optionen zur Generierung des Autors und der Version benötigt. Die Optionen erlauben die Informationen über Autoren und Versionen auf Wunsch wegzulassen:

 $ javadoc -author -version  Ware.java 

Das Kommando erzeugt eine Reihe von html Dateien im gleichen Verzeichnis. Die generierte Datei index.html sieht wie folgt aus (Screen shot):