Titel | Inhalt | Suchen | Index | DOC | Handbuch der Java-Programmierung, 3. Auflage
<< | < | > | >> | API | Kapitel 50 - Hilfsprogramme des JDK

## 50.5 javadoc - Der Dokumentationsgenerator

- 50.5 javadoc - Der Dokumentationsgenerator
  - 50.5.1 Aufruf
  - 50.5.2 Beschreibung
  - 50.5.3 Dokumentationskommentare
  - 50.5.4 Aufruf von javadoc
  - 50.5.5 Optionen

### 50.5.1 Aufruf

    javadoc [ options ] { package | sourcefile }

### 50.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.

### 50.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 50.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 50.5: Markierungen in Dokumentationskommentaren

### 50.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.4

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.4

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.4\docs (und somit die API-Dokumentation im Verzeichnis c:\jdk1.4\docs\api), kann `javadoc` wie folgt aufgerufen werden:

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

### 50.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 50.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.4

Titel | Inhalt | Suchen | Index | DOC | Handbuch der Java-Programmierung, 3. Auflage, Addison Wesley, Version 3.0
<< | < | > | >> | API | © 1998-2002 Guido Krüger, http://www.javabuch.de