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.

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.

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