6.15 Dokumentationskommentare mit javaDoc
 
Die 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 in einer öffentlichen Bibliothek anderen Entwicklern zur Verfügung stellen und wieder verwenden. Um die Klassen und Funktionen gut finden und nutzen zu können, müssen die Schnittstellen sorgfältig beschrieben werden. Wichtig bei der Beschreibung sind der Klassenname, der Methodenname, die Art und die Anzahl der Parameter, die Wirkung der Funktionen und das Laufzeitverhalten. Da das Erstellen einer externen Dokumentation – also einer Beschreibung außerhalb der Quellcodedatei – fehlerträchtig und deshalb nicht gerade motivierend für die Beschreibung ist, werden spezielle Dokumentationskommentare in den Java-Quelltext eingeführt. Ein spezielles Programm generiert aus den Kommentaren Beschreibungsdateien wie HTML mit den gewünschten Informationen.1
 6.15.1 Einen Dokumentationskommentar setzen
 
In einer besonders ausgezeichneten Kommentarumgebung werden die Dokumentationskommentare (»Doc Comments«) eingesetzt. Die Kommentarumgebung erweitert ein Blockkommentar und ist vor allen Typen (Klassen, Schnittstellen, Aufzählungen) sowie Methoden und Variablen üblich.
Im folgenden Beispiel gibt Java-Doc Kommentare für die Klasse, Attribute und Methoden an.
Listing 6.85
com/javatutor/insel/javadoc/Disko.java
package com.javatutor.insel.javadoc;
/**
* Modelliert eine Disko.
*/
public class Disko
{
/** Anzahl Personen in der Disko */
int anzahlPersonen;
/**
* Person betritt in die Disko.
* Erhöht den internen Zähler für die Anzahl Besucher.
*/
void personRein() {
anzahlPersonen++;
}
/**
* Person verlässt die Disko.
* Vermindert den internen Zähler für die Anzahl Besucher.
*/
void personRaus() {
if ( anzahlPersonen > 0 )
anzahlPersonen--;
}
/**
* Liefert die Anzahl Personen in der Disko.
*
* @return Anzahl Personen.
*/
int anzahlPersonen() {
return anzahlPersonen;
}
}
Hinweis Die Dokumentationskommentare sind so aufgebaut, dass der erste Satz in der Auflistung der Methoden und Attribute erscheint und der Rest in der Detailansicht.
/**
* 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() { }
|
Da ein Dokumentationskommentar /** mit /* beginnt, ist es für den Compiler ein normaler Blockkommentar. Die javaDoc-Kommentare werden oft optisch aufgewertet, indem am Anfang ein Sternchen steht. Dieses wird von javaDoc ignoriert.
6.15.2 Mit javadoc eine Dokumentation erstellen
 
Aus dem mit Kommentaren versehenen Quellcode generiert ein externes Programm die Zieldokumente. Sun liefert beim SDK das Konsolen-Programm javadoc mit, dem als Parameter ein Dateiname der zu kommentierenden Klasse übergeben wird; aus compilierten Dateien können natürlich keine Beschreibungsdateien erstellt werden. Wir starten javadoc im Verzeichnis, in dem auch die Klassen liegen, und erhalten unsere HTML-Dokumente.
Beispiel Möchten wir Dokumentationen für das gesamte Verzeichnis erstellen, so geben wir alle Dateien mit der Endung .java an:
$ javadoc *.java
|
javaDoc geht durch den Quelltext, parst die Deklarationen und zieht die Dokumentation heraus. Daraus generiert das Tool eine Beschreibung, die in der Regel als HTML-Seite zu uns kommt.

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.
6.15.3 HTML-Tags in Dokumentationskommentaren
 
In den Kommentaren können HTML-Tags verwendet werden, beispielsweise <b>bold</b> und <i>italic</i>, um Textattribute zu setzen. Sie werden direkt in die Dokumentation übernommen und müssen 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.

In Eclipse zeigt die View javadoc in einer Vorschau das Ergebnis des Dokumentationskommentars an.
6.15.4 Generierte Dateien
 
Für jede öffentliche Klasse erstellt javaDoc eine HTML-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. |
6.15.5 Weitere Dokumentationskommentare
 
Tabelle 6.3
Die wichtigsten Dokumentationskommentare im Überblick
Kommentar
|
Beschreibung
|
@see Klassenname
|
Verweis auf eine andere Klasse
|
@see Klassenname oder Methodenname
|
Verweis auf eine andere Methode
|
@see Ausgeschriebener Klassenname
|
Verweis auf eine voll qualifizierte Klasse
|
@see Ausgeschriebener Klassenname oder Methodenname
|
Verweis auf eine voll qualifizierte Methode
|
@version Versionstext
|
Version
|
@author Autor
|
Schöpfer
|
@return Rückgabetext
|
Rückgabewert
|
@param Parametername oder Parametertext
|
Beschreibung der Parameter
|
@exception Exception-Klassenname oder Exceptiontext
|
Ausnahmen, die ausgelöst werden können
|
@throws Exception-Klassenname oder
Exceptiontext
|
Synonym zu oben
|
{@link Verweis }
|
Einen eingebauten Verweis im Text. Parameter sind wie bei @see.
|
Beispiele
Beispiele: Eine externe Zusatzquelle angeben:
@see <a href="spec.html#section">Java Spec</a>.
Verweis auf eine Funktion, die mit der beschriebenen Funktion verwandt ist:
@see String#equals(Object) equals
Dokumentiere eine Variable. Gib einen Verweis auf eine Methode an:
/**
* The X-coordinate of the component.
*
* @see #getLocation()
*/
int x = 1263732;
Eine veraltete Methode, die auf eine Alternative zeigt:
/**
* @deprecated As of JDK 1.1,
* replaced by {@link #setBounds(int,int,int,int)}
*/
|
6.15.6 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 ein eigenes Doclet programmieren oder kann auf Doclets unterschiedlicher Hersteller zurückgreifen. Die Webseite http://www.doclet.com/ listet zum Beispiel Doclets auf, die Docbook generieren oder UML-Diagramme mit aufnehmen.
Daneben dient ein Doclet aber nicht nur der Schnittstellendokumentation. Ein Doclet kann auch aufzeigen, ob es zu jeder Methode eine Dokumentation gibt oder ob jeder Parameter und jeder Rückgabewert korrekt beschrieben ist. Auch zur Generierung zusätzlicher Programmdateien und XML-Deskriptoren können Doclets verwendet werden. XDoclet (http://xdoclet.sourceforge.net/) ist ein populäres Beispiel, wie aus annotiertem Quellcode Mappings-Dateien für relationale Datenbanken generiert oder für Enterprise Java Beans Dateien abgeleitet werden.
6.15.7 Veraltete (deprecated) Klassen, Konstruktoren und Methoden
 
Während der Phase eines Programms ändert sich die Sicht auf die Methoden, und das laufende Angebot eines Objekts oder einer Klasse muss unter Umständen eingeschränkt und verändert werden. Gründe gibt es viele:
|
Methoden können nicht wirklich plattformunabhängig programmiert werden, wurden aber einmal angeboten. Nun soll die Methode nicht mehr unterstützt werden. (Ein Beispiel ist die Methode stop() eines Threads.) |
|
Die Java-Namenskonvention soll eingeführt und ältere Methodennamen sollen nicht mehr verwendet werden. Das betrifft in erster Linie spezielle setXXX()/getXXX()-Methoden, die seit Version 1.1 eingeführt wurden. So finden wir beim AWT viele Beispiele dafür. Nun heißt es zum Beispiel statt size() bei einer grafischen Komponente getSize(). |
|
Entwickler haben sich beim Methodennamen verschrieben. So hieß es in FontMetrics vorher getMaxDecent() und nun getMaxDescent(), und im HTMLEditorKit wird insertAtBoundry() zu insertAtBoundary(). |
Hinweis Veraltetes hat sich im Laufe der Zeit angesammelt; in Java 5 sind über 300 Methoden/Konstruktoren, etwas mehr als 50 Variablen/Konstanten, 21 Klassen (zuzüg-lich 4 Execptions) und 16 Schnittstellen.
|
Es ist ungünstig, die Methoden jetzt einfach zu löschen, denn dann kommt es zu Compilerfehlern. Eine Lösung wäre daher, die Methode beziehungsweise den Konstruktor deprecated zu deklarieren. Deprecated ist ein eigener Dokumentationskommentar; das sieht dann etwa so aus (Ausschnitt aus der Klasse java.util.Date):
/**
* Sets the day of the month of this <tt>Date</tt> object to the
* specified value. ….
*
* @param date the day of the month value between 1–31.
* @see java.util.Calendar
* _saito_fett_ @deprecated As of JDK version 1.1,
* replaced by <code>Calendar.set(Calendar.DAY_OF_MONTH, int date)</code>.
_saito_fettout_ */
public void setDate(int date) {
setField(Calendar.DATE, date);
}
Die Kennung @deprecated gibt an, dass die Methode/der Konstruktor nicht mehr verwendet werden soll. Ein guter Kommentar gibt auch Alternativen an, sofern vorhanden. Die Alternative, die hier genannt wird, ist die Methode set() aus dem Calendar-Objekt. Da das Kommentar in die generierte API-Dokumentation übernommen wird, erkennt der Entwickler, dass eine Methode veraltet ist.
Hinweis Wenn die Kennung einer Methode »veraltet« anlastet, heißt das noch nicht, dass es sie nicht mehr geben muss. Es ist nur ein Hinweis, dass die Methoden nicht mehr verwendet werden sollten und Unterstützung nicht mehr gegeben ist.
|
Beispiel Der Compiler gibt bei veralteten Methoden eine kleine Meldung auf dem Bildschirm aus. Testen wir das an der Klasse AlterSack.
Listing 6.86
AlterSack.java
public class AlterSack
{
java.util.Date d = new java.util.Date( 62, 3, 4 );
}
|
Jetzt rufen wir ganz normal den Compiler auf.
$ javac AlterSack.java
Note: AlterSack.java uses or overrides a deprecated API.
Note: Recompile with -deprecation for details.
Der Compiler sagt uns schon, was wir machen können: Der Schalter -deprecation zeigt uns mehr. Was wird das wohl sein?
$ javac -deprecation AlterSack.java
AlterSack.java:5: warning: Date(int,int,int) in java.util.Date has been deprecated
Date d = new Date( 62, 3, 4 );
^
1 warning
Die Ausgabe gibt genau die Zeile mit der veralteten Anweisung an. Alternativen nennt er nicht. Allerdings ist schon interessant, dass der Compiler in die Dokumentationskommentare sieht. Er gibt jedoch keine Alternativen an. Eigentlich hat er mit den auskommentierten Blöcken nichts zu tun und überliest jeden Kommentar. Für die speziellen Kommentare gibt es das Extra-Tool Javadoc, das wiederum mit dem Java-Compiler nichts zu tun hat.
Hinweis Auch Klassen lassen sich als deprecated kennzeichnen (siehe etwa java.io.LineNumberInputStream). Dies finden wir jedoch selten, und es sollte vermieden werden.
|
Die Annotation @Deprecated
Seit Java 5 gibt es Annotationen, die zusätzliche Modifizierer sind. Eine Annotation @Deprecated (groß geschrieben) ist vordefiniert und ermöglicht es ebenfalls, Dinge als veraltet zu kennzeichnen. Dazu wird die Annotation wie ein üblicher Modifizierer etwa für Methoden vor den Rückgabetyp gestellt. Sun hat die oben genannte Funktion setDate() mit dieser Annotation gekennzeichnet, wie es der folgende Ausschnitt zeigt:
/** ...
* @deprecated As of JDK version 1.1,
* replaced by <code>Calendar.set(Calendar.DAY_OF_MONTH, int date)</code>.
*/
@Deprecated
public void setDate(int date) { ... }
1 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.
|