07.04.03 javadoc – Klassen dokumentieren

Kommentare wurden bereits im Kapitel 02.01 Kommentare erläutert. Die dort erwähnten JavaDoc Kommentare sind für dieses Kapitel relevant. Lesen Sie deshalb bei Bedarf noch einmal im entsprechenden Kapitel nach. Denn aus ihnen können Sie vollautomatisch eine Java-Dokumentation, wie Sie sie von der API-Dokumentation von Oracle kennen, erzeugen.

Erstellen Sie sich zu Testzwecken eine einfache Klasse und versehen selbige mit einem JavaDoc-Kommentar:

public class SimpleMath {

  /**
   * Teilt einen Integer-Wert durch einen Anderen.
   */
  public int divide(int dividend, int divisor) {
    return dividend / divisor;
  }
}

Navigieren Sie sich nun auf der Konsole (wie als wollten Sie die Klasse ausführen oder kompilieren) in das Verzeichnis dieser Klasse und rufen Sie das Programm javadoc mit dem Parameter SimpleMath.java auf.

javadoc SimpleMath.java

Sollte der Befehl javadoc nicht gefunden werden, liegt das vermutlich daran, dass Ihre PATH-Umgebungsvariable nicht richtig gesetzt wurde. Lesen Sie hierzu im Kapitel 01.03 Java installieren nach.

Es werden in diesem Verzeichnis eine Vielzahl an Dateien generiert. Öffnen Sie die index.html-Datei mit einem Browser Ihrer Wahl. Sie werden eine ganz gewöhnliche Java-Dokumentation – nur eben für Ihre eigene Klasse – sehen.

Formatierungen der JavaDoc

Bevor ich Ihnen die Parameter für das javadoc-Programm näher erläutern werde, sehen wir uns erst einmal an, wie Sie Einfluss auf die Formatierung der Dokumentation nehmen können. Verwenden Sie bspw. normale HTML-Tags wie <strong>, <em> oder <code> im Kommentar, werden diese entsprechend übernommen.

public class SimpleMath {

  /**
   * <strong>Teilt</strong> einen <code>Integer</code>-Wert 
   * <em>durch</em> einen Anderen.
   */
  public int divide(int dividend, int divisor) {
    return dividend / divisor;
  }
}

Dies ist aber nur die Spitze des Eisbergs. Sie können auch detailliert weitere Eigenarten dokumentieren. Diese nennt man Tags.

Java Dokumentation Tags

Diese Tags spezifizieren z. B. welche Parameter erwartet werden, was zurück gegeben wird, welche Exception geworfen werden kann, oder ob die Methode veraltet ist (hier sollte selbstverständlich ab Java 1.5 zusätzlich noch die Annotation @Deprecated verwendet werden). Hierfür wird immer das dazugehörige Schlüsselwort nach einem @ geschrieben. Anschließend folgt die dazugehörige Beschreibung.

public class SimpleMath {

  /**
   * Teilt einen <code>Integer</code>-Wert durch einen Anderen.
   *
   * @param dividend
   *           Zahl, die geteilt werden soll.
   * @param divisor
   *           Zahl, durch die geteilt werden soll.
   * @return Den Quotienten dieser Rechnung.
   * @throws java.lang.ArithmeticException
   *           Falls der Divisor gleich 0 ist.
   * @deprecated Methode ist veraltet, da sie keinen Rest
   *             berücksichtigt.
   */
  @Deprecated
  public int divide(int dividend, int divisor) {
    return dividend / divisor;
  }
}

Die Kommentare beschränken sich aber nicht nur lediglich auf diese vier Tags, anbei finden Sie eine Übersicht der verfügbaren Tags. Gleichzeitig befindet sich die Auflistung in der Reihenfolge, wie die Tags gesetzt werden sollten.

Tag Beschreibung
@param Definiert einen Parameter (für Klassen, Interfaces, Methoden und Konstruktoren)
@return Rückgabewert einer Methode
@exception, @throws Fehler, die geworfen werden können
@author Verfasser der Klasse oder des Interfaces
@version Version der Klasse oder des Interfaces
@see Definiert Codeblöcke (Methoden, Klassen, …), die in diesem Zusammenhang auch noch wichtig sind
@since Seit welcher Version existiert der Code
@serial Beschreibung für ein serialisierbares Feld
@deprecated Kennzeichnet eine Methode als veraltet, siehe auch Deprecated

Beim @see-Tag können Sie verlinkten Java-Code in folgender Form angeben:

@see #attribut // Verweis auf ein Attribut der eigenen Klasse
@see #Konstruktor(Type, Type, ...) // Verweis auf einen Konstruktor mit den angegebenen Parametertypen
@see #methode(Type, Type, ...) // Verweis auf eine Methode mit den angegebenen Parametertypen
@see Class // Verweis auf eine Klasse
@see Class#attribut
@see Class#Konstruktor(Type, Type, ...)
@see Class#methode(Type, Type, ...)
@see package // Verweis auf ein Package
@see package.Class
@see package.Class#attribut
@see package.Class#Konstruktor(Type, Type, ...)
@see package.Class#methode(Type, Type, ...)

Sie können auch außerhalb des @see-Tags in der JavaDoc verlinken. Verwenden Sie hierfür {@link verlinkterCode}.

public class SimpleMath {

  /**
   * Teilt einen <code>Integer</code>-Wert durch einen Anderen.
   *
   * @param dividend
   *           Zahl, die geteilt werden soll.
   * @param divisor
   *           Zahl, durch die geteilt werden soll.
   * @return Den Quotienten dieser Rechnung.
   * @throws java.lang.ArithmeticException
   *           Falls der Divisor gleich 0 ist.
   * @deprecated Methode ist veraltet, da sie keinen Rest
   *             berücksichtigt. Ersetzt durch {@link #divide(float, float)}
   */
  @Deprecated
  public int divide(int dividend, int divisor) {
    return dividend / divisor;
  }

  /**
   * Teilt einen <code>Integer</code>-Wert durch einen Anderen.
   *
   * @param dividend
   *           Zahl, die geteilt werden soll.
   * @param divisor
   *           Zahl, durch die geteilt werden soll.
   * @return Den Quotienten dieser Rechnung.
   */
  public float divide(float dividend, float divisor) {
    return dividend / divisor;
  }
}

Eine weiterführende Referenz der Dokumentation-Tags finden Sie bei Sun direkt.

Zu guter Letzt werfen wir noch einen Blick auf die wichtigsten Übergabeparameter des javadoc-Tools.

Parameter Beschreibung
-public Dokumentiert lediglich Code, der als öffentlich markiert wurde.
-protected Dokumentiert lediglich Code, der als öffentlich oder geschützt markiert wurde (Standard).
-package Dokumentiert lediglich Code, der als öffentlich, geschützt, oder paketsichtbar markiert wurde.
-private Dokumentiert jeden Code.
-version Spezifiziert die Version.
-author Legt den Autor fest.
-d Verzeichnis Ordner, in welchem die Dokumentationsdateien gespeichert werden sollen.
-verbose Ausgabe zusätzlicher Statusmeldungen während der Dokumentationserstellung.
-classpath Pfad Spezifiziert den Classpath.

Sie müssen natürlich nicht für jede einzelne zu dokumentierende Klasse das javadoc-Tool aufrufen. Sie können ebenfalls Wildcards übergeben. Auf diesem Weg ist es bspw. möglich, alle *.java-Dateien mit einem Schlag zu dokumentieren.

javadoc *.java

Previous Article
Next Article

2 Replies to “07.04.03 javadoc – Klassen dokumentieren”

  1. Anonymus

    Der vierte Parameter (in der Tabelle am Ende) ist vermutlich private. Das package zwei verschiedene Aktionen ausführt ist unwahrscheinlich.

Schreibe einen Kommentar

Diese Website verwendet Akismet, um Spam zu reduzieren. Erfahre mehr darüber, wie deine Kommentardaten verarbeitet werden.