Java Standard: Javadoc

Zurück zu Assertions | Hoch zu Java Inhaltsverzeichnis | Vor zu Objektorientierung

Programmdokumentation ist ein leidiges Thema: Lästig und zeitraubend. Wozu man einen Quelltext kommentiert erschließt sich ja sehr schnell: Es dauert nicht lange, und man hat vergessen, wozu dieser oder jener Code fähig ist und was der Trick dabei war. Aber Programmierungen entstehen heute meist als Teamwork. Java ist durch seinen modularen Aufbau, wie alle objektorientierten Programmiersprachen, in besonderem Maße dafür vorgesehen; die einzelnen Klassen sind so gestaltet, dass man nur noch wissen muss, was sie leisten und wie man sie bedient. Aber das bedeutet, dass man eine Dokumentation schreiben muss.

Wäre es nicht wunderbar, wenn man das während der Programmierung gleich erledigen könnte? Vielleicht direkt im Quelltext, so dass man auch gleich selbst eine Dokumentation seiner Klasse besitzt?

Genau das leistet Javadoc, das Dokumentationsprogramm des Java-Systems.

Javadoc liest den Quellcode eines Projektes ein, analysiert die vorhandenen Methoden und Funktionen auf Parameter und Rückgabewerte und produziert daraus eine Dokumentation der Klassen des Paketes. Im einfachsten Fall entsteht eine HTML-Aufstellung für jede einzelne Klasse, die public-Methoden auflistet und deren Parameter und Rückgabewerte aufführt. Werden die Namenskonventionen eingehalten und werden möglichst sprechende Namen für die übergebenen Parameter gewählt entstehen ohne zusätzlichen Aufwand bereits hilfreiche Basis-Angaben.

Selbstverständlich ist es zudem möglich (und sinnvoll), diese Basisdokumentation um Erläuterungen zu erweitern. Das wird auf zwei Weisen verwirklicht: Zum Einen können Texte eingepflegt werden, die wie die "privaten" Kommentare geschrieben werden können. Zum Anderen werden durch spezielle Schlüsselworte auch Ergänzungen für die automatischen Analysen ermöglicht. Dabei werden zwei Bereiche unterschieden: Zunächst der Kopf der Klasse, in dem die Aufgabe der Klasse beschrieben wird und mit Schlüsselworten zusätzliche Angaben wie die Versionsnummer oder der Autor der Klasse hinterlegt werden. Der zweite Bereich ist die detaillierte Beschreibung von Variablen sowie der einzelnen Methoden mit ihren Parametern und Rückgabewerten. Auch hier sind neben den Beschreibungen zusätzlich Schlüsselworte vorgesehen.

Kommentare für den Programmierer

Wer bereits in anderen Programmiersprachen gearbeitet hat kennt die beiden folgenden Kommentarformen wahrscheinlich bereits; sie sind der verbreiteten Programmiersprache C++ entnommen und werden in Java genauso gehandhabt wie dort. Die erste Variante ist der kurze Kommentar, der mit einem // eingeleitet wird und den Rest der Zeile umfasst. Damit kann man gut ein kurzes Stichwort hinterlegen oder eine Programmzeile auskommentieren:

// Mit den vorgesetzten Kommentarzeichen wird count vom Compiler ignoriert
// int count;

Wird die Variable später benötigt werden die Kommentarzeichen entfernt:

// count wird in dieser Variante vom Compiler als Variable erkannt
int count;

Die zweite Variante ermöglicht mehrzeilige Kommentare. So lassen sich nicht nur große Texte in den Quelltext einpflegen, sondern auch größere Programmstücke auskommentieren, zum Beispiel Methoden, die derzeit nicht benötigt werden. Dieser Kommentartyp verfügt über ein Anfangs- und ein Ende-Zeichen, das aus einem Schrägstrich und einem Sternchen besteht:

/* Kommentar */

oder auch:

/*
Kommentar
*/

Achtung: Werden mehrere solche Kommentare ineinander verschachtelt führt das zu einem Fehler. Sobald das erste "Kommentarende"-Zeichen gefunden wird hält der Compiler den kompletten Kommentar für beendet. Da er den Text nach dem "Kommentarstart"-Zeichen nur noch nach dem Ende-Zeichen durchsucht und alle weiteren Texte ignoriert erkennt er nicht, dass ein zweiter Kommentar eingesetzt wurde. Folgende Konstruktion ist also falsch:

/* int count; /* count wird erst in einer folgenden Version benötigt */ Hier ist der Kommentar bereits zu Ende */

Als Beispiel für die Verwendung dieser beiden Kommentartypen möge ein - leicht modifizierter - Code aus dem Kapitel über Arrays dienen:

 public class JavaArrayTest1 {
	/* Array definieren */
	private double [] value;
  
	// Konstruktor; hier wird der Platz für das Array reserviert
	public JavaArrayTest1() {
		value = new double [10];   
	}
   
	/* Methode zum Setzen eines Array-Wertes. Der Index wird überprüft.
	Wenn der Index außerhalb des Gültigkeitsbereichs liegt wird der Aufruf ignoriert. */
	public void setValue(int index, double wert) {
		if(index >= 0 && index < value.length)
			value [index] = wert;
	}
   
	/*Methode zur Abfrage eines Array-Wertes. Der Index wird überprüft.
	  Wenn der Index außerhalb des Gültigkeitsbereichs liegt wird der Wert 0.0 zurück geliefert. */
	public double getValue(int index) {
		double result = 0.0;

		if(index >= 0 && index < value.length)
			result = value [index];

		return result;
	}  
 }

Alle Kommentare, die auf diese Weise in den Programmcode gesetzt werden, bleiben von Javadoc unberührt. Sie erscheinen nicht in der Dokumentation, die von Javadoc erstellt wird.

Beschreibungen für den Anwender der Klasse

Um einem Nachnutzer der Klasse die Arbeit zu erleichtern analysiert Javadoc den Quelltext der Klasse bzw. des Pakets und erstellt daraus eine Reihe von HTML-Dateien. In ihnen werden die Informationen gesammelt, die Javadoc erkennt und die für einen Programmierer, der Ihre Arbeit nicht kennt, von Interesse sein können. In der Grundeinstellung sind das alle Methoden und Variablen, die als public definiert sind. Auf andere Werte kann ein Programmierer ohne Kenntnis des Aufbaus Ihrer Programmierung nicht zugreifen; daher ist diese Einschränkung auch sinnvoll. Die Ausgabe lässt sich aber durch Kommandozeilenparameter ändern (in den üblichen grafischen Entwicklungsumgebungen gibt es dafür menügesteuerte Einstellungen). Von diesen Steuerungsmöglichkeiten wird weiter unten im Detail die Rede sein.

Die automatische Auswertung lässt sich durch Angaben des Programmierers ergänzen. Dazu gehören neben den unten besprochenen Parametern auch zusätzliche Kommentierungen, die zu jeder Klasse, zu jeder Variablen und zu jeder Methode gemacht werden können. Diese Kommentare, in die auch die zusätzlichen Schlüsselworte eingegliedert werden, haben eigene Kommentarzeichen. Javadoc-Kommentare werden mit einem Schrägstrich und zwei Sternchen begonnen: /** (im Gegensatz zu den Blockkomentaren für Programmierer, die einen Schrägstrich mit einem einzelnen Sternchen benutzen: /*). Das Kommentarende-Zeichen entspricht dagegen dem Endezeichen des Blockkommentars: */. Interne Blockkommentare für Programmierer und für das Javadoc-System lassen sich also ebenfalls nicht ineinander verschachteln.

Bei der Auswertung der Kommentare werden in den Übersichten, etwa in den Beschreibungen eines Paketes, in dem die zugehörigen Klassen aufgeführt werden oder in der Dokumentation einer Klasse, zu der eine Übersicht über Variablen und Methoden hinter der Klassenbeschreibung gehört, der jeweils erste Satz der Beschreibung übernommen. Daher sollte der Kommentator darauf achten, die wichtigsten Aufgaben in seinem ersten Satz zusammenzufassen.

Hinweis: Die Sprache des Programmierers ist Englisch. In den folgenden Beispielen sind deswegen alle Kommentare und Parameterbeschreibungen in Englisch gehalten. Da die Nutzung von Java-Klassen und -Paketen häufig grenzüberschreitend abläuft empfehle ich, diesem Beispiel in den eigenen Programmierungen zu folgen. Die Ausgabe von Javadoc ist ebenfalls auf die englische Sprache ausgerichtet.

Da die Namen der Klassen, Variablen und Methoden ebenfalls in der Dokumentation aufgeführt werden ist es empfehlenswert, auch hier die englische Sprache zu verwenden und die Funktion möglichst gut beschreibende Bezeichner zu nutzen; sie erleichtern dem Nachnutzer das Verständnis der Funktionsweise der Klasse und können die zusätzlichen Beschreibungen des Codes deutlich verkürzen. Hinweise für die Konventionen finden Sie im Kapitel zum Programmierstil unter Java.

Allgemeine Informationen über die Klasse

Um die Angaben zu vervollständigen kann die Klassenbeschreibungen durch spezielle Tags angereichert werden. Dies sind die Angaben zum Autoren der Klasse (@author), zur Version der Klasse (@version) und zur Angabe, seit wann die Klasse im Paket vorhanden ist (@since). Zusätzlich können noch allgemeingültige Tags benutzt werden, zum Beispiel das @depricated-Tag für Klassen, die veraltet sind und nicht mehr genutzt werden sollten, aber aus Gründen der Kompatibilität im Paket belassen wurden. Diese allgemeinen Tags werden in einem eigenen Abschnitt weiter unten besprochen.

Das folgende Beispiel nutzt lediglich eine leere Klassendefinition; es geht hier ausschließlich um den Kommentar vor der Programmierung.

/**
** This class is designed to test Arrays. It uses the console to present the result and supports 
** 
** @author Max Mustermann
** @version 1.0.2
** @since version 1.0.0
*/
 public class JavaArrayTest1 {
 }

Spezielle Informationen zu Methoden

	/** 
	 ** Method to set a value at a specified index.
         **
	 ** @param index An <code>int</code>-Value in the range of 0 to 9. Other values are ignored.
         ** @param value A <code>double</code> with the value to set.
         ** @see #getValue(int)
	 */
	public void setValue(int index, double value) {
		if(index >= 0 && index < value.length)
			value [index] = wert;
	}
   
	/** 
	 ** Method to get a stored value.
         **
         ** @param index An <code>int</code>-Value in the range of 0 to 9. Other values are ignored.
         ** @return The stored value as a <code>double>, or 0 in case of an invalid index.
         ** @see #setValue(int, double)
         */
	public double getValue(int index) {
		double result = 0.0;

		if(index >= 0 && index < value.length)
			result = value [index];

		return result;
	}  
 }

Liste der Dokumentations-Parameter

Die folgende Übersicht enthält alle Tags, die in Javadoc der Java-Version 12 verfügbar sind. Sie sind alle spätestens ab Java-Version 5.0 implementiert.

Einige Tags werden von einfachen geschweiften Klammern umgeben, zum Beispiel das Tag {@code Text}. Diese geschweiften Klammern müssen mit eingegeben werden. Sie zeigen an, wie weit das Tag reicht. Das ist notwendig, weil die betreffenden Tags im normalen Javadoc-Kommentar eingefügt werden und damit das Zeilenende den Geltungsbereich des Tags nicht begrenzt, wie es bei den Tags ohne die geschweiften Klammern der Fall ist.

Kopf

• @author Name– Fügt den Autor als eigene Zeile in die Beschreibung der Klasse ein. Das Tag wird im Normalfall ignoriert und muss in der Entwicklungsumgebung oder auf der Kommandozeile mit der Option -author aktiviert werden.
• @since Version– Version, seit der die Funktionalität existiert. Dabei wird der Parameter Version als Text in die Dokumentation aufgenommen. Der Tag erzeugt eine eigene Zeile.
• @version Version– Erzeugt einen Versionseintrag mit dem übergebenen Text als Versionsnummer als eigene Zeile. Das Tag darf pro Klasse nur einmal verwendet werden. Es wird im Normalfall ignoriert und muss in der Entwicklungsumgebung oder auf der Kommandozeile mit der Option -version aktiviert werden.

Variablen

• @serial– Bei der Verwendung des Interfaces Serializable kann es sinnvoll sein, die betreffenden Variablen gesondert zu beschreiben. Dieses Tag wird zur Dokumentation für einzelne Variablen verwendet und produziert eine eigene Zeile in der Dokumentation.
• @serialField– Entspricht dem Tag @serial, wird aber für die Dokumentation von Arrays verwendet.

Methoden und Funktionen

• @exception Exception Beschreibung– funktionsgleich zu @throws; siehe unten.
• @param Name Beschreibung– Hinterlegt eine Beschreibung des Parameters „Name“ in einer eigenen Zeile der Dokumentation. Hier sollten Sie auch den Typ der Variablen und mögliche Einschränkungen der Gültigkeit hinterlegen. Verwenden Sie für jeden Parameter ihrer Methode ein eigenes @param-Tag.
• {@inheritDoc}– Kopiert die Beschreibung aus der überschriebenen Methode. Das Tag wird ignoriert, wenn keine Methode überschrieben wurde. Es wird im Fließtext der Methodenbeschreibung platziert.
• @return Beschreibung– In einer eigenen Zeile der Dokumentation kann der Rückgabewert der Methode beschrieben werden.
• @throws Exception Beschreibung – Wenn eine Methode eine Exception wirft kann dieses Tag genutzt werden, um eine Beschreibung des auslösenden Fehlers zu hinterlegen. Dabei wird von Javadoc keine Prüfung ausgeführt, ob die Methode eine Exception deklariert. Dadurch können auch Methoden dokumentiert werden, die geworfene Exceptions nicht deklarieren. Einen Hinweis auf die undeklarierte Exception sollten Sie zusätzlich in der Beschreibung der Methode geben.

Übergreifend verwendbar

• {@code Text}– Formatiert den Text „wie er ist“; HTML-Codes und Javadoc-Tags werden belassen, wie sie sind. Der Tag wird im Fließtext eingebettet. {@code} formatiert den hinterlegten Text in einer anderen Schriftart als den Fließtext; um dieselbe Schriftart zu generieren wird das Tag {@literal} verwendet.
• @deprecated Beschreibung– Beschreibt eine veraltete Methode, die nicht mehr verwendet werden sollte, die aber aus Kompatibilitätsgründen in dem Paket belassen wurde. Der Tag erzeugt eine eigene Zeile in der Dokumentation. In der Beschreibung sollte angegeben werden, welche Klasse, Variable oder Methode die veraltete Programmierung ersetzt.
• {@docRoot}– Fügt den Pfad zum Hauptverzeichnis in den Fließtext ein.
• {@link Verweis}– Funktioniert wie das Tag @see, wird aber im Fließext eingebettet.
• {@linkPlain Verweis}– Wie der Tag {@link}, aber die Verlinkung wird in der normalen Schriftart des Fließtextes eingefügt.
• {@literal Text}– Funktioniert wie der Tag {@code}, formatiert den Text aber in der Standardschriftart des Fließtextes.
• @see Verweis– Erzeugt einen Verweis auf ein anderes Element der Dokumentation. Das Ziel wird mit einem # begonnen, wenn es eine Methode oder eine Variable ist. Bei Methoden ist es auch wichtig, die Parametertypen aufzuführen, um an die korrekte Stelle zu springen. Besonders wichtig ist dies, wenn mehrere Methoden gleichen Namens, aber mit unterschiedlichen Parametern vorliegen. Ein Anwendungsbeispiel finden Sie weiter oben. Der Tag erzeugt eine eigene Zeile in der Dokumentation; für einen Verweis im Fließtext wird das Tag {@ link} verwendet.
• {@value Variablenname}– Fügt den Wert einer statischen Variable im Fließtext ein. Dabei ist zu beachten, dass die Variable auch sichtbar sein muss; zum Beispiel wird ein als private gekennzeichneter Wert mit den Standardeinstellungen für Javadoc übergangen. Auch wenn die Variable nicht existiert wird der Tag ignoriert.

Erweiterungen des Systems

Javadoc ist ein eigenständiges Programm, das in der "normalen" API mitgeliefert wird und durch die Übergabe von Kommandozeilenparametern gesteuert wird. Es analysiert die übergebenen Dateien und produziert aus ihnen HTML-Dateien. Was aber, wenn Ausgaben im PDF-Format (oder als RTF oder was auch immer) benötigt werden? Oder wenn zusätzliche oder völlig andere Schlüsselworte eingepflegt werden sollen?

Auch das ist prinzipiell möglich. Javadoc ist selbst in Java geschrieben; der Quellcode ist verfügbar und kann verändert werden. So lassen sich zum Beispiel Änderungen in der Auswertung von Schlüsselworten oder zusätzliche Steuerungsmöglichkeiten einbauen. Die andere Möglichkeit ist, ein komplettes eigenes Javadoc zu schreiben, wenn man Wert auf ein komplett anderes Ausgabeformat legt.

Diese Programmierungen zu beschreiben übersteigt aber den Rahmen dieser Einleitung. Die Aufgabe ist auch nicht trivial und für einen Einsteiger vielleicht ein wenig Zuviel. Hier muss der Hinweis genügen, dass es auch diese Möglichkeit gibt.

Zurück zu Assertions | Hoch zu Java Inhaltsverzeichnis | Vor zu Objektorientierung