JavaDoc - Tutorial

Was ist JavaDoc?
Wie erstelle ich JavaDoc?
JavaDoc in den JBuilder einbinden
Richtig dokumentieren & Tags
Wichtige Optionen
Related Links

Was ist JavaDoc?

Javadoc ist ein Programm, das aus Java-Quelltexten Dokumentationen im HTML-Format erstellt. Dazu verwendet es die öffentlichen Klassen-, Interface- und Methodendeklarationen und fügt zusätzliche Informationen aus eventuell vorhandenen Dokumentationskommentaren hinzu. Zu jeder Klassendatei xyz.java wird eine HTML-Seite xyz.html generiert, die über verschiedene Querverweise mit den anderen Seiten desselben Projekts in Verbindung steht. Zusätzlich generiert Javadoc diverse Index- und Hilfsdateien, die das Navigieren in den Dokumentationsdateien erleichtern.

Wie erstelle ich JavaDoc?

Die Erstellung von JavaDoc erfolgt durch den Aufruf des JavaDoc-Programmes, welches mit dem JDK mitgeliefert wird. Die formale Syntax ist

javadoc [ options ] { package | sourcefile }

Zur Erstellung von JavaDoc für ein Projekt xyz wechselt man in das /src/xyz-Verzeichnis dieses Projektes und gibt folgenden Programmaufruf ein:

javadoc *.java

Alternativ zum Aufruf mit einer Reihe von Quelldateien kann javadoc auch mit Paketnamen als Argument aufgerufen werden. Wenn der Klassenpfad korrekt gesetzt ist, spielt es dann keine Rolle mehr, aus welchem Verzeichnis das Programm gestartet wird, denn die Klassendateien werden automatisch korrekt gefunden. Wenn nicht per Option -d etwas anderes angegeben wurde, erzeugt javadoc die Dokumentationsdateien im aktuellen Verzeichnis.

JavaDoc in den JBuilder einbinden

Es ist auch möglich JavaDoc als Tool in den JBuilder einzubinden. Hiermit vermeidet man die Komandozeilennutzung und kann JavaDoc bequem aus dem JBuilder heraus generieren lassen.

Zum Einrichten geht man auf Tools | Configure Tools... und wählt die Option Add... aus.
Im folgenden Fenster gibt man dem Tool unter Title einen sprechenden Namen (z.B. JavaDoc).
Man wählt mit Hilfe des Datei-Browsers (...) unter Program das JavaDoc Program aus. Unter Solaris ist dieses im Pfad /bin/javadoc und unter Windows im JDK-Verzeichnis, üblicherweise C:\Programme\JBuilder4\jdk1.3\bin\javadoc.exe zu finden.
Die unter Parameters zu übergebenen Parameter sind (unter Solaris mit "/" statt "\"):
-d ($ProjectDir)\doc -sourcepath ($ProjectDir)\src ($FilePath)
Jetzt muss man sich nur noch im Projekt-Verzeichnis ein Unterverzeichnis /doc anlegen und kann durch Auswählen des JavaDoc-Tools im Menü Tools JavaDoc erstellen.
Zur effizienteren Arbeit kann man sich das JavaDoc vom JBuilder anzeigen lassen (im Quelltextfenster den Reiter Doc auswählen und den entsprechenden Pfad angeben). So muss man nicht nebenbei einen Browser laufen lassen.
Hinweis: Das so erstellte Tool kann mit den Windows-Pfaden nicht richtig umgehen. Am besten vermeidet man es, dass einer der übergebenen Pfade ein Leerzeichen enthält (z.B. nicht das Projekt unter c:\Eigene Dateien\... speichern)

Richtig dokumentieren & Tags

Bereits ohne zusätzliche Informationen erstellt javadoc aus dem Quelltext eine brauchbare Beschreibung aller Klassen und Interfaces. Durch das Einfügen von Dokumentationskommentaren kann die Ausgabe zusätzlich bereichert werden. Ein Dokumentationskommentar beginnt mit /** und endet mit */ und ähnelt damit einem gewöhnlichen Kommentar. Er muß im Quelltext immer unmittelbar vor dem zu dokumentierenden Item plaziert werden (einer Klassendefinition, einer Methode oder einer Instanzvariable). Er kann aus mehreren Zeilen bestehen. Die erste Zeile des Kommentars wird später als Kurzbeschreibung verwendet.
Zur Erhöhung der Übersichtlichkeit darf am Anfang jeder Zeile ein Sternchen stehen, es wird später ignoriert. Innerhalb der Dokumentationskommentare dürfen neben normalem Text auch HTML-Tags vorkommen. Sie werden unverändert in die Dokumentation übernommen und erlauben es damit, bereits im Quelltext die Formatierung der späteren Dokumentation vorzugeben. Die Tags <h1> und <h2> sollten möglichst nicht verwendet werden, da sie von JavaDoc selbst zur Strukturierung der Ausgabe verwendet werden.
JavaDoc erkennt des weiteren markierte Absätze innerhalb von Dokumentationskommentaren, sog. Tags. Die Tags muß mit dem Zeichen @ beginnen und - abgesehen von Leerzeichen - am Anfang der Zeile stehen. Jeder Tag leitet einen eigenen Abschnitt innerhalb der Beschreibung ein, alle Tags eines Typs müssen hintereinanderstehen.
Wichtige Tags:

Markierung und Parameter Dokumentation Verwendung in

@author name Erzeugt einen Autoreneintrag. Klasse, Interface

@version version Erzeugt einen Versionseintrag. Darf höchstens einmal je Klasse oder Interface verwendet werden. Klasse, Interface

@since JDK-Version Beschreibt, seit wann das beschriebene Feature existiert Klasse, Interface

@see reference Erzeugt einen Querverweis auf eine andere Klasse, Methode oder einen beliebigen anderen Teil der Dokumentation. Gültige Verweise sind z.B.:

@see java.util.Vector
@see Vector
@see Vector#addElement
Klasse, Interface, Instanzvariable, Methode

@param name description Parameterbeschreibung einer Methode Methode

@return description Beschreibung des Rückgabewerts einer Methode Methode

@exception classname description Beschreibung einer Ausnahme, die von dieser Methode geworfen wird Methode

@deprecated description Markiert eine veraltete Methode, die zukünftig nicht mehr verwendet werden sollte. Methode

Wichtige Optionen

Option	Bedeutung
`-classpath path`	Gibt die Liste der Pfade zur Suche von Klassendateien an
`-public`	Nur Elemente des Typs public werden dokumentiert
`-protected`	Elemente des Typs public und protected werden dokumentiert (das ist die Voreinstellung)
`-package`	Elemente des Typs package, public und protected werden dokumentiert
`-private`	Alle Elemente werden dokumentiert
`-version`	VersionseinTRag generieren
`-author`	AutoreneinTRag generieren
`-sourcepath path`	Pfad mit den Quelldateien
`-d directory`	Verzeichnis, in dem die generierten Dokumentationsdateien abgelegt werden. Standardmäßig werden sie im aktuellen Verzeichnis angelegt.
`-verbose`	Ausgabe zusätzlicher Meldungen während der Dokumentationserstellung