25.4 Mit JavaDoc und Doclets dokumentieren

Dokumentation von Softwaresystemen ist ein wichtiger, aber oft vernachlässigter Teil der Softwareentwicklung. Im Entwicklungsprozess müssen die Entwickler Zeit in Beschreibungen der einzelnen Komponenten investieren, besonders dann, wenn weitere Entwickler diese Komponenten wieder verwerten. Diese Wiederverwertung wird besonders bei der objektorientierten Programmierung angestrebt. Deshalb müssen die Schnittstellen sorgfältig beschrieben werden. Wichtig bei der Beschreibung sind die Art und die Anzahl der Parameter, die Wirkung der Funktionen und das Laufzeitverhalten. Da das Erstellen einer externen Dokumentation - also eine Beschreibung außerhalb der Quellcodedatei - fehlerträchtig und deshalb nicht gerade motivierend für die Beschreibung ist, werden spezielle Anweisungen in den Java-Quelltext eingeführt. Ein spezielles Programm generiert aus den Formatierungsanweisungen eine Textdatei mit den gewünschten Informationen.¹

25.4.1 Mit JavaDoc Dokumentationen erstellen

JavaDoc geht durch den Quelltext und parst die Deklarationen und zieht die Dokumentation heraus. Daraus generiert das Tool eine Beschreibung, die in der Regel als HTML-Seite zu uns kommt. Die Dokumentation beschreibt die Klassen (auch innere), die Vererbung, die Methoden und Attribute, die Konstruktoren und Schnittstellen.

Aus den Beschreibungen im Java-Quelltext werden folgende Informationen zusammengetragen:

Kopf

Diagramm der Klassenhierarchie

Klassenbeschreibung

Index der Public-Variablen

Index der Public-Methoden

Index der Konstruktoren

Beschreibung der Public-Variablen

Beschreibung der Public-Konstruktoren

Beschreibung der Public-Methoden

25.4.2 Wie JavaDoc benutzt wird

In einer besonders ausgezeichneten Kommentarumgebung werden die beschreibenden Anweisungen, Dokumentationskommentare (»Doc Comments«), eingesetzt. Die Kommentarumgebung ähnelt dem Blockkommentar.

/**
 * Socken sind spezielle Kleidungsstücke.
 */
public class Socke extends Kleidung
{
}

Da ein Dokumentationskommentar /** mit /* beginnt, ist es für den Compiler ein normaler Blockkommentar. Die Kommentare werden oft optisch aufgewertet, indem am Anfang ein Sternchen steht. Dieses wird von JavaDoc ignoriert.

/**
 *   Das ist ein kurzer Satz.
 *   Das ist die ausführliche Beschreibung.
 *   Die ausführliche Beschreibung erscheint
 *   später im Abschnitt "Method Detail".
 *   Der kurze Satz erscheint im Abschnitt "Method Summary".
 */
public void foo() { }

Dokumentationskommentare

Tabelle 25.3 Die wichtigsten Dokumentationskommentare im Überblick

@see <a href="spec.html#section">Java Spec.

@see String#equals(Object) equals

/**
 * The X-coordinate of the component.
 *

 * @see #getLocation()
 */
 int x = 1263732;

/**
 * @deprecated  As of JDK 1.1,
 * replaced by {@link #setBounds(int,int,int,int)}
 */

HTML-Tags in Dokumentationskommentaren

In den Kommentaren können HTML-Tags verwendet werden, beispielsweise <b>..</b> und <i>..</i>, um Textattribute zu setzen. Sie werden direkt in die Dokumentation übernommen, müssen also korrekt geschachtelt sein, damit die Ausgabe nicht falsch dargestellt wird. Die Überschriften-Tags <h1>..</h1> und <h2>..</h2> sollten jedoch nicht verwendet werden. JavaDoc verwendet sie zur Gliederung der Ausgabe und weist ihnen Formatvorlagen zu.

25.4.3 Eine Dokumentation erstellen

Um eine Dokumentation zu erzeugen, wird dem Konsolen-Programm javadoc als Parameter ein Dateiname der zu kommentierenden Klasse übergeben; aus compilierten Dateien können natürlich keine Beschreibungsdateien erstellt werden.

Listing 25.1 Kleidung.java

/**
 *  Kleidung bildet die Oberklasse für alle Kleidungs-Objekte.
 */
import java.io.*;
public abstract class Kleidung implements Serializable
{
  /**
   *  Jede Kleidung hat eine Farbe.
   */
  protected String farbe;
  /**
   *  Erzeugt neues Kleidungs-Objekt.
   */
  protected Kleidung()
  {
  }
  /**
   *  Erzeugt neues Kleidungs-Objekt,
   *  welches mit einer Farbe initialisiert wird.
   */
  protected Kleidung( String farbe )
  {
    this.farbe = farbe;
  }
  /**
   *  Jede Kleidung hat einen Namen.
   *  Wird von Unterklassen überschrieben.
   */
   abstract String getName();
}

Listing 25.2 Socke.java

/**
 *  Socken sind spezielle Kleidungsstücke.
 */
import java.io.*;
public class Socke extends Kleidung implements Serializable
{
  /**
   *  Erzeugt ein neues Socken-Objekt mit der Farbe Schwarz.
   */
   Socke()
   {
     super( "schwarz" );
   }
   /**
    *  Überschrieben von der Oberklasse.
    */
    public String getName()
    {
      return "Socke";
    }
}

Wir starten javadoc im Verzeichnis, in dem auch die Klassen liegen, und erhalten eine Reihe von HTML-Dokumenten.

$ javadoc *.java

Hier klicken, um das Bild zu Vergrößern

In Eclipse lässt sich eine Dokumentation mit JavaDoc sehr einfach erstellen. Im Menü File, Export ist der Eintrag Javadoc zu wählen und nach ein paar Einstellungen ist die Dokumentation generiert.

Generierte Dateien

Für jede öffentliche Klasse erstellt JavaDoc eine HMTL-Datei. Sind Klassen nicht öffentlich, muss ein Schalter angegeben werden. Die HTML-Dateien werden zusätzlich mit Querverweisen zu den anderen dokumentierten Klassen versehen. Daneben erstellt JavaDoc weitere Dateien:

index-all.html Die Übersicht aller Klassen, Schnittstellen, Ausnahmen, Methoden und Felder in einem Index

overview-tree.html Zeigt in einer Baumstruktur die Klassen an, damit die Vererbung deutlich sichtbar ist.

allclasses-frame.html Anzeige aller dokumentierten Klassen in allen Unterpaketen

deprecated-list.html Liste der veralteten Methoden und Klassen

serialized-form.html Listet alle Klassen auf, die Serializable implementieren. Jedes Attribut erscheint mit einer Beschreibung in einem Absatz.

help-doc.html Eine Kurzbeschreibung von JavaDoc

index.html JavaDoc erzeugt eine Ansicht mit Frames. Das ist die Hauptdatei, die die rechte und linke Seite referenziert. Die linke Seite ist die Datei allclasses-frame.html. Rechts im Frame wird bei fehlender Paketbeschreibung die erste Klasse angezeigt.

stylesheet.css Formatvorlage für HTML-Dateien, in der sich Farben und Zeichensätze einstellen lassen, die dann alle HTML-Dateien nutzen.

packages.html Eine veraltete Datei. Sie verweist auf die neuen Dateien.

Schalter für das Programm javadoc

Über die umfangreichen Parameter informiert eine HTML-Datei, die dem Java-SDK beigelegt ist.

WINDOWTITLE = 'Java Platform 1.2 Final API Specification'
DOCTITLE = 'Java<font size="-2">TM</font> Platform 1.2 Final\
 API Specification'
HEADER = '<b>Java Platform 1.2</b><font size="-1">Final</font>'
BOTTOM = '<font size="-1"><a href=">http://java.sun.com/cgi-bin/\
 bugreport.cgi">Submit a bug or featureJava is a\
 trademark or registered trademark of Sun Microsystems, Inc. in the\
 US and other countries.Copyright 1993-1998 Sun Microsystems,\
 Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A.\
 All Rights Reserved.</font>'
GROUPCORE = '"Core Packages" "java.*:com.sun.java.*:org.omg.*"
GROUPEXT  = '"Extension Packages" "javax.*"'
javadoc -sourcepath /jdk/src/share/classes \
        -d /jdk/build/api                  \
        -use                               \
        -splitIndex                        \
        -windowtitle $(WINDOWTITLE)        \
        -doctitle $(DOCTITLE)              \
        -header $(HEADER)                  \
        -bottom $(BOTTOM)                  \
        -group $(GROUPCORE)                \
        -group $(GROUPEXT)                 \
        -overview overview-core.html       \
        -J-Xmx180m                         \
        java.lang java.lang.reflect        \
        java.util java.io java.net         \
        java.applet                        \

25.4.4 JavaDoc und Doclets

Die Ausgabe von JavaDoc kann den eigenen Bedürfnissen angepasst werden, indem Doclets eingesetzt werden. Ein Doclet ist ein Java-Programm, das auf der Doclet-API aufbaut und die Ausgabedatei schreibt. Das Programm liest dabei wie das bekannte JavaDoc-Tool die Quelldateien ein und erzeugt daraus ein beliebiges Ausgabeformat. Dieses Format kann selbst gewählt und implementiert werden. Wer also neben dem von JavaSoft beigefügten Standard-Doclet für HTML-Dateien Framemaker-Dateien (MIF) oder RTF-Dateien erzeugen möchte, muss nur ein eigenes Doclet programmieren. Daneben dient ein Doclet aber nicht nur der Schnittstellendokumentation. Ein Doclet kann auch dokumentieren, ob es zu jeder Methode auch eine Dokumentation gibt oder ob jeder Parameter und jeder Rückgabewert beschrieben ist.

¹ Die Idee ist nicht neu. In den Achtzigerjahren verwendete Donald E. Knuth das WEB-System zur Dokumentation von TeX. Das Programm wurde mit den Hilfsprogrammen weave und tangle in ein Pascal-Programm und eine TeX-Datei umgewandelt.