49.5 javadoc - Der Dokumentationsgenerator

• 49.5 javadoc - Der Dokumentationsgenerator
  • 49.5.1 Aufruf
  • 49.5.2 Beschreibung
  • 49.5.3 Dokumentationskommentare
  • 49.5.4 Aufruf von javadoc
  • 49.5.5 Optionen

49.5.1 Aufruf

javadoc [ options ] { package | sourcefile }

49.5.2 Beschreibung

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.

49.5.3 Dokumentationskommentare

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.

Hinweis

javadoc erkennt des weiteren markierte Absätze innerhalb von Dokumentationskommentaren. Die Markierung muß mit dem Zeichen @ beginnen und - abgesehen von Leerzeichen - am Anfang der Zeile stehen. Jede Markierung leitet einen eigenen Abschnitt innerhalb der Beschreibung ein, alle Markierungen eines Typs müssen hintereinanderstehen. Tabelle 49.5 gibt eine Übersicht der wichtigsten Markierungen und beschreibt, wie sie verwendet werden.

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: @see java.util.Vector @see Vector @see Vector#addElement @see <a href="Spez.html">Spez</a>	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 ausgelöst wird	Methode
@deprecated description	Markiert eine veraltete Methode, die zukünftig nicht mehr verwendet werden sollte.	Methode

Tabelle 49.5: Markierungen in Dokumentationskommentaren

49.5.4 Aufruf von javadoc

Um javadoc aufzurufen, sollte zunächst in das Verzeichnis gewechselt werden, in dem sich die zu dokumentierenden Quelldateien befinden. Anschließend kann durch Eingabe des folgenden Kommandos die Erzeugung der Dokumentationen für alle Quelldateien gestartet werden:

javadoc *.java

Das Programm erzeugt eine Reihe von HMTL-Dateien, die die zu den jeweiligen Quellen korrespondierenden Dokumentationen enthalten. Zusätzlich werden eine Reihe von Hilfsdateien zur Darstellung und Indexierung der Dokumentationsdateien erstellt.

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 Schalter -d etwas anderes angegeben wurde, erzeugt javadoc die Dokumentationsdateien im aktuellen Verzeichnis.

In den JDKs 1.0 und 1.1 erzeugt javadoc zwei unterschiedliche Arten von Standardverweisen. Bei der ersten Art werden Grafiken eingebunden, um Überschriften für die verschiedenen Dokumentationsabschnitte zu generieren. Damit diese im Browser korrekt angezeigt werden, muß ein Unterverzeichnis images angelegt und die erforderlichen Grafikdateien dorthin kopiert werden (beispielsweise aus \jdk1.1.2\docs\api\images). Ab dem JDK 1.2 werden dagegen keine Grafikdateien mehr benötigt.

JDK1.1-1.3

Die zweite Art von Verweisen ist die auf Klassen oder Methoden der Java-Klassenbibliothek (z.B. java.lang.String). Im JDK 1.1 geht javadoc davon aus, daß sich die Dokumentationsdateien zu allen externen Klassen und Methoden im selben Verzeichnis wie die zu erstellenden Dokumentationsdateien befinden. Damit also externe Verweise funktionieren, müßte man die HTML-Files der Originaldokumentation des JDK in sein eigenes Dokumentationsverzeichnis kopieren, was sicherlich nicht immer praktikabel ist.

Mit dem JDK 1.2 wurde die Option -link eingeführt, mit der ein Pfad auf die Dokumentation der Standardklassen angegeben werden kann. Der Pfad muß als URL angegeben werden und das Verzeichnis beschreiben, in dem die Datei package-list der Dokumentationsdateien liegt. In der Dokumentation zu javadoc gibt SUN folgendes Beispiel an: javadoc -link http://java.sun.com/products/jdk/1.2/docs/api ...

JDK1.1-1.3

Dadurch wird bei Standard-Klassennamen auf die auf dem SUN-Server liegende Originaldokumentation verwiesen. Soll dagegen auf eine lokal installierte Dokumentation verwiesen werden, kann auch ein file-URL angegeben werden. Liegt die Dokumentation des JDK beispielsweise im Verzeichnis c:\jdk1.3\docs (und somit die API-Dokumentation im Verzeichnis c:\jdk1.3\docs\api), kann javadoc wie folgt aufgerufen werden:

javadoc -link file:///c:/jdk1.3/docs/api ...

49.5.5 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

Tabelle 49.6: Einige Optionen von javadoc

Neben den hier erwähnten Schaltern kennt javadoc (insbesondere seit dem JDK 1.2) eine ganze Reihe zusätzlicher Optionen, mit denen die Codeerzeugung beeinflußt werden kann. Bemerkenswert ist dabei auf jeden Fall das Konzept der Doclets, mit denen das Verhalten von javadoc und das Aussehen der generierten Dokumentationsdateien weitgehend verändert werden kann. Doclets sind Zusatzmodule für javadoc, deren Aufgabe es ist, auf der Basis des Doclet-APIs und der geparsten Quelltexte die Ausgabedateien zu erzeugen. Ob der generierte Code dabei im HTML-, RTF- oder einem anderen Format erzeugt wird, spielt keine Rolle. Das seit dem JDK 1.2 ausgelieferte Standard-Doclet erzeugt die Dokumentationsdateien im HTML-Format.

JDK1.1-1.3