javadoc ist ein Dokumentationsgenerator. Er erzeugt anhand von Java-Quelltexten eine Dokumentation, in der die jeweiligen Klassen, Interfaces, Methoden, Konstruktoren und Datenelemente aufgeführt sind.

Als Argument bekommt javadoc einen Paketnamen oder die Namen von Java-Quelltexten übergeben. Auch die bei javac beschriebene @-Syntax zum Einlesen von Listen wird unterstützt.

Seit Version 1.2 ist es möglich, die Dokumentation mit selbstdefinierten Klassen, den so genannten Doclets, zu generieren. Hierbei analysiert javadoc die zu dokumentierenden Klassen und macht dem Doclet die ermittelten Informationen über das API des Pakets com.sun.javadoc zugänglich. Auf diese Weise kann sich die Implementierung der Doclets auf die äußerliche Darstellung der Dokumentation konzentrieren. javadoc beinhaltet ein Standard-Doclet, das eine HTML-Dokumentation erzeugt.

Doclets können eigene Optionen haben. Daher gibt es sowohl Optionen von javadoc selbst, die immer verfügbar sind, als auch Doclet-abhängige Optionen. Nachfolgend sind zunächst die Optionen von javadoc aufgeführt, gefolgt von den Optionen des Standard-Doclets.

javadoc besitzt folgende Optionen:

• -overview <file>
  stellt <file> als Übersichtsseite der Dokumentation ein. <file> sollte gültigen HTML-Code enthalten.
• -public
  nimmt nur als public deklarierte Klassenelemente in die Dokumentation auf.
• -protected
  nimmt alle als public und protected deklarierten Bestandteile in die Dokumentation auf. Diese Option ist voreingestellt.
• -package
  nimmt alle Bestandteile in die Dokumentation auf, die als public, protected oder mit voreingestelltem Zugriff vereinbart sind.
• -private
  nimmt alle Klassenelemente in die Dokumentation auf.
• -help
  listet die vorhandenen Optionen auf.
• -doclet <class>
  erlaubt es, ein Doclet anzugeben, das die Dokumentation erzeugt. Die Hauptklasse des Doclets wird durch <class> angegeben. Ohne Angabe dieser Option wird die Ausgabe mit dem Standard-Doclet formatiert, das mit dem SDK mitgeliefert wird.
• -docletpath <classpathlist>
  gibt den Pfad an, in dem die Hauptklasse des Doclets liegt, das mit der Option -doclet angegeben wurde. Liegt die Hauptklasse bereits im herkömmlichen Klassenpfad, muss diese Option nicht angegeben werden, auch wenn -doclet benutzt wird.
• -sourcepath <pathlist>
  gibt die Pfade an, in denen javadoc nach Quelltexten sucht. Mehrere Pfade müssen durch ; (Windows) bzw. : (UNIX) getrennt werden.
• -classpath <path>
  Gibt das Verzeichnis an, in dem javadoc nach Quelltext-Dateien sucht. Diese Option setzt die CLASSPATH-Umgebungsvariable außer Kraft. Mehrere Pfade müssen durch ; (Windows) bzw. : (UNIX) getrennt werden.
• -bootclasspath <bootclasspath>
  Mit dieser Option kann der Pfad geändert werden, unter dem die System-Klassen gesucht werden. Mehrere Pfade müssen durch ; (Windows) bzw. : (UNIX) getrennt werden.
• -extdirs <dirlist>
  Mit dieser Option können Verzeichnisse angegeben werden, in denen nach Erweiterungspaketen gesucht wird. Mehrere Pfade müssen durch ; (Windows) bzw. : (UNIX) getrennt werden. javadoc sucht in diesem Pfaden auch nach Quelltexten.
• -verbose
  Falls diese Option gesetzt ist, wird ausgegeben, welche Dateien bearbeitet und geladen werden.
• -locale <locale>
  ermöglicht die Angabe einer Sprache für die generierte Dokumentation. Hierdurch ist es möglich, die Navigationsleiste sprachspezifisch anzupassen. <locale> wird wie bei der Klasse Locale üblich im Format <l>_<c> angegeben, wobei <l> das Kürzel der Sprache und <c> das Kürzel des Landes ist (z.B. de_DE),
• -encoding <enc>
  erlaubt es anzugeben, in welcher Zeichenkodierung die Quelltexte vorliegen. Wenn man diese Option nicht angibt, wird die Standardkodierung für die verwendete Plattform angenommen. Gültige Werte für <enc> können dem Anhang D entnommen werden.
• -J<flag>
  ermöglicht es, eine Option an den Interpreter zu übergeben, in dem javadoc ausgeführt wird. Für jede durchzureichende Option muss -J separat angegeben werden. Zwischen -J und <option> darf kein Leerzeichen sein (z.B. -J-verbose).

Das mitgelieferte Standard-Doclet, das die Formatierung der Dokumentation übernimmt, stellt zusätzlich folgende Optionen zur Verfügung:

• -d <directory>
  Mit dieser Option kann man das Verzeichnis angeben, in dem die erzeugten HTML-Dateien gespeichert werden sollen. Per Voreinstellung wird das aktuelle Verzeichnis verwendet.
• -use
  fügt der Dokumentation für jede Klasse eine Seite hinzu, auf der vermerkt ist, wo die Klasse in den dokumentierten Paketen benutzt wird.
• -version
  fügt der Dokumentation den Wert des @version-Tags hinzu.
• -author
  Fügt der Dokumentation die Werte der @author-Tags hinzu.
• -splitindex
  spaltet den Index in mehrere Dateien auf. Für jeden Anfangsbuchstaben wird eine neue Datei erzeugt.
• -windowtitle <title>
  gibt den Titel an, der in der Titelleiste des Browsers beim Laden der Dokumentation angezeigt wird.
• -doctitle <title>
  definiert den Titel, der in der generierten Dokumentation im Allgemeinen Überblick erscheint. <title> kann auch HTML-Tags enthalten.
• -header <header>
  gibt den Text an, der bei jeder generierten HTML-Seite am Seitenkopf erscheint. <header> kann auch HTML-Tags enthalten.
• -footer <footer>
  gibt den Text an, der an der rechten Seite der unteren Navigationsleiste erscheint. <footer> kann auch HTML-Tags enthalten.
• -bottom <text>
  Bei Angabe dieser Option wird <text> an den unteren Rand der generierten HTML-Seiten unter der Navigationsleiste angefügt. <text> sollte gültigen HTML-Text enthalten.
• -link <url>
  erzeugt in der Dokumentation Links zu bereits bestehenden Javadoc-Dokumenten. Beim Erzeugen der Dokumentation werden per Voreinstellung in der Dokumentation nur Verweise zu den Klassen aufgelöst, die beim aktuellen javadoc-Durchlauf dokumentiert werden. Benutzt man diese Option, können auch Links zu Klassen aufgelöst werden, die nicht beim aktuellen Durchlauf dokumentiert werden. Hierzu muss <url> eine URL auf das Basisverzeichnis (relativ oder absolut) der bereits erzeugten Javadoc-Dokumentation enthalten. Beim Aufruf prüft javadoc, ob die angegebene URL erreicht werden kann.
• -linkoffline <docurl> <packagelisturl>
  arbeitet im Prinzip wie -link mit dem Unterschied, dass die referenzierte Dokumentation keine package-list-Datei im Basisverzeichnis enthalten muss. Ab JDK 1.2 erzeugt javadoc im Basisverzeichnis der generierten Dokumentation eine Datei namens package-list, in der alle Pakete aufgelistet sind, die die Dokumentation enthält. Bei dieser Option kann man explizit den Pfad zur package-list URL angeben. Außerdem wird bei der Option -linkoffline die Erreichbarkeit der URLs nicht geprüft.
• -linksource
  Integriert eine HTML-Version des Quelltexts in die jeweilige Dokumentationsseite.
• -group <groupheading>
  <packagepattern>:<packagepattern>...
  ermöglicht die Einteilung der Pakete in Gruppen, die auf der Übersichtsseite angezeigt werden. Für jede neu definierte Gruppe muss eine eigene -group-Option angegeben werden. Die Gruppen werden auf der Seite in der Reihenfolge angezeigt, in der sie in der Kommandozeile erscheinen. <groupheading> sollte den Namen der Gruppen enthalten, <packagepattern> gibt die Klassen an, die einer Gruppen angehören (z. B. java.lang.*). Gehören einer Gruppe mehrere Pakete an, dann sind diese mit einem Doppelpunkt zu trennen.
• -nodeprecated
  unterdrückt die Generierung von Dokumentation für Methoden, die als »deprecated« gekennzeichnet sind.
• -nodeprecatedlist
  unterdrückt die Generierung einer Liste, in der alle als »deprecated« gekennzeichneten Methoden aufgelistet sind. Es wird auch kein Link von der Navigationsleiste auf diese Liste erstellt. Diese Option wird meist benutzt, wenn die Klassen gar keine als »deprecated« gekennzeichneten Methoden enthalten.
• -notree
  unterdrückt die Generierung der Klassen-/Interface-Hierarchie.
• -noindex
  unterdrückt die Generierung eines Index. Per Voreinstellung wird der Index generiert.
• -nohelp
  unterdrückt die Generierung des Links auf die Hilfeseite in der Navigationsleiste.
• -nonavbar
  unterdrückt die Generierung einer Navigationsleiste sowie Kopf- und Fußzeile. Diese Option kann nur sinnvoll eingesetzt werden, wenn keine Navigation benötigt wird, wie z. B. in der Aufbereitung für den Ausdruck.
• -helpfile <helpfile>
  gibt eine Hilfedatei an, zu der der Help-Link in der Navigationsleiste weist. Wenn man diese Option nicht angibt, wird die mit dem SDK mitgelieferte Hilfedatei verwendet. <helpfile> gibt den Pfad zu einer Datei an, die gültigen HTML-Text enthalten sollte.
• -stylesheetfile <stylesheet>
  ermöglicht die Angabe eines eigenen Stylesheets, mit dem die Dokumentation dargestellt wird.
• -docencoding <enc>
  gibt an, in welchem Zeichensatz die Ausgabedatei gespeichert wird. Gültige Werte für <enc> können dem Anhang D entnommen werden.
• -serialwarn
  Erzeugt Warnungen, wenn bei serialisierbaren Klassen @serial-Tags fehlen.
• -source <version>
  Diese Option muss mit dem Wert 1.4 angegeben werden, wenn Quelltext dokumentiert werden sollen, die Zusicherungen verwenden.
• -tag <name>:<scope>:<label>
  Mit dieser Option kann das anwenderdefinierte Tag <name> mit dem Text <label> in der Dokumentation angezeigt werden. Der Parameter <scope> wird durch die folgenden Werte gebildet und legt fest, in welchen Teilen das Tag angezeigt wird:

  Tabelle 74.1: Tag-Anzeige

  x	Keine Anzeige des Tags (exclude)
  a	An allen Stellen (all)
  o	In der Einstiegsseite (overview)
  p	In der Einstiegsseite eines Pakets (package)
  t	Bei Klassen und Interfaces (types)
  c	Bei Konstruktoren
  m	Bei Methoden
  f	Bei Datenelementen

  Einzelne Werte können auch verkettet werden, zum Beispiel cmf. Beispiel:

    -tag status:c:Status
  

  Diese Option zeigt alle Vorkommen des Tags @status auf Klassenebene mit dem Text »Status« an.
• -taglet <class>
  Spezifiziert die Klasse <class> zur Darstellung von javadoc-Tags.
• -tagletpath <pathlist>
  Definiert einen Suchpfad, unter dem die Klassen für Taglets zu finden sind.
• -subpackages <package>
  Bewirkt, dass die Dokumentation nicht nur für das Paket <package>, sondern auch für alle Unterpakete erzeugt wird. Ausnahmen hiervon können mit -exclude gemacht werden.
• -exclude <package1[:package2...]>
  Schließt die übergebenen Pakete von der Generierung aus.
• -docfilessubdirs
  Bewirkt, dass das Verzeichnis doc-files vom jeweiligen Quelltext-Verzeichnis rekursiv in das Zielverzeichnis kopiert wird. Dies ist beispielsweise zur Einbindung von Bildern in die Dokumentation nützlich. Ausnahmen können mit -excludedocfilessubdirs definiert werden.
• -excludedocfilessubdirs <dir1[:dir2...]>
  Schließt die angegebenen Unterverzeichnisse der mit -docfilessubdirs spezifizierten Verzeichnisse vom Kopiervorgang aus. So könnte man mit

  -docfilessubdirs -excludedocfilessubdirs images/draft
  

  bewirken, das alle Dateien im Unterverzeichnis images kopiert werden, nicht aber die Entwürfe im Verzeichnis images/draft.
• -noqualifier all¦<package1[:package2...]>
  Schaltet die volle Qualifizierung von Klassennamen mit dem jeweiligen Paketnamen im angegebenen Bereich ab.
• -nocomment
  Unterdrückt die Ausgabe aller Kommentartexte. Die Dokumentationsseiten werden lediglich mit den strukturellen Bestandteilen erzeugt.

Innerhalb von Kommentaren in Quelltexten kann man spezielle Anweisungen für javadoc einfügen, die so genannten javadoc-Tags. Durch diese Tags kann man zusätzliche Informationen in die erzeugte Dokumentation einbringen und Querverweise zwischen Methoden einbinden. Die Tags beginnen alle mit dem Zeichen @. Im Folgenden werden die wichtigsten Tags aufgeführt. Zur Dokumentation von Klassen können folgende Tags verwendet werden:

• @author <author>
  erzeugt einen Eintrag mit dem Label »author«.
• @see <classname>
  fügt der Klasse einen Verweis zu <classname> zu.
• @see <classname>#<methodname>
  fügt der Klasse einen Verweis auf die Methode <methodname> der Klasse <classname> hinzu.
• @version <text>
  Mit diesem Tag kann der Programmierer Informationen über die Version seiner Klasse angeben. Der <text> erscheint in der HTML-Seite mit dem Label »version«.

Mit folgenden Tags können Methoden dokumentiert werden:

• @param <name> <description>
  Dient zur Dokumentation der Parameter. <name> entspricht dem Parameternamen, <description> der Bedeutung eines Parameters.
• @return <description>
  Dient zur Dokumentation des Rückgabewertes einer Methode. <description> erklärt den Rückgabewert.
• @exception <name> <description>
  @throws <name> <description>
  Dient der Dokumentation von Exceptions, die von einer Methode erzeugt werden können. <name> gibt den Namen der ausgelösten Exception an, <description> erläutert, wann diese Exception ausgelöst wird.
• @deprecated <text>
  Mit diesem Tag werden veraltete Methoden gekennzeichnet. In <text> kann man z. B. einen Text angegeben, der den Grund für die Verwerfung nennt und eine bessere Alternative aufzeigt.

Bei Datenelementen kann zusätzlich zu den Tags @see, @since und @deprecated das Tag @value verwendet werden, das den Wert von konstanten Datenelementen anzeigt. An jeder Stelle können die folgenden Tags zur Erzeugung von Verweisen verwendet werden:

• @see <link>
  Erzeugt einen Verweis auf <link>. <link> kann dabei ein statischer Text oder auch ein voll qualifizierter Klassen- oder Methodenname sein. In diesem Fall wird ein Hyper-Link erzeugt. Für Verweise auf Methoden muss die Methoden-Signatur vom voll qualifizierten Klassennamen durch ein # getrennt werden:

    @see java.lang.System#exit(int) exit()
  

  Wie das Beispiel zeigt, kann optional ein Text angehängt werden, mit dem der Link dargestellt wird (in diesem Fall exit()).
• @link <link>
  Erzeugt einen Verweis an der Stelle des Tags. <link> hat das gleiche Format wie @see <link>. Es wird die Schriftart zur Darstellung von Quelltexten verwendet.
• @linkplain <link>
  Dieses Tag unterscheidet sich von @link lediglich dadurch, dass der Text des Verweises in normaler Schriftart dargestellt wird.