JavaDoc

Javadoc ist ein Software-Dokumentationswerkzeug, das aus Java-Quelltexten automatisch HTML-Dokumentationsdateien erstellt. Javadoc wurde ebenso wie Java von Sun Microsystems entwickelt und ist seit Version 2 ein Bestandteil des Java Development Kits.

Die Dokumentation kann somit durch spezielle Kommentare im Quelltext erstellt werden. Dadurch können Beschreibungen für Interfaces, Klassen, Methoden und Felder über spezielle Doclet-Tags definiert werden.

Funktionsweise

Javadoc erhält beim Aufruf Optionen mit Angaben über die zu dokumentierenden Java-Quelltexte. Javadoc parst die Quelltexte nach allen Javadoc-Kommentaren (beginnend mit /**) und den darauf folgenden, nicht-lokalen Symbolen. Jeder Javadoc-Kommentar wird nach darin enthaltenen Javadoc-Tags (beginnend mit @ oder {@) gescannt. Diese enthalten Metadaten mit dokumentativem Charakter über das jeweilige Symbol. Mit Hilfe sogenannter Taglets kann der bestehende Tag-Wortschatz von Javadoc erweitert werden. Das Doclet erzeugt anschließend die Ausgabe. Das Standard-Doclet erzeugt eine Ausgabe in HTML. Es existieren aber auch weitere Doclets, um die Dokumentation in anderen Formaten wie RTF, XML, PDF, Framemaker, Windows Help und einigen mehr zu erzeugen.

Beispiel-Quelltext

/**
 * Ein Hello-World-Programm in Java.
 * Dies ist ein Javadoc-Kommentar.
 *
 * @author John Doe
 * @version 1.0
 */
public class Hello {
 
    /** 
     * Hauptprogramm.
     *
     * @param args Kommandozeilenparameter
     */
    public static void main(String[] args) {
        System.out.println("Hallo, Welt!");
    }
 
}

Beispiel-Ausgabe

Ein Beispiel für die Ausgabe von Javadoc ist die Java-API-Dokumentation von Sun (s. Weblinks), die mit Hilfe von Javadoc erstellt wurde.

Übersicht der Javadoc-Tags

Tag & Parameter	Ausgabe	Verwendung in
@author name	Beschreibt den Autor.	Klasse, Interface
@version version	Erzeugt einen Versionseintrag. Maximal einmal pro Klasse oder Interface.	Klasse, Interface
@since jdk-version	Seit wann die Funktionalität existiert.	Klasse, Interface, Instanzvariable, Methode
@see reference	Erzeugt einen Link auf ein anderes Element der Dokumentation.	Klasse, Interface, Instanzvariable, Methode
@param name description	Parameterbeschreibung einer Methode.	Methode
@return description	Beschreibung des Returnwerts einer Methode.	Methode
@exception classname description @throws classname description	Beschreibung einer Exception, die von dieser Methode geworfen werden kann.	Methode
@deprecated description	Beschreibt eine veraltete Methode, die nicht mehr verwendet werden sollte. Sollte ab Java 5.0 immer mit der @Deprecated-Annotation verwendet werden.	Methode
{@inheritDoc}	Kopiert die Beschreibung aus der überschriebenen Methode	Überschreibende Methode
{@link reference}	Link zu einem anderen Symbol	Klasse, Interface, Instanzvariable, Methode
{@code}	Formatiert Text buchstabengetreu mit dem Quelltextzeichensatz (entsprechend <code>) und unterdrückt die Interpretierung von beinhalteten HTML oder Javadoc-Tags.	Klasse, Interface, Instanzvariable, Methode
{@literal}	Kennzeichnet buchstabengetreuen Text und unterdrückt die Interpretierung von beinhalteten HTML oder Javadoc-Tags.	Klasse, Interface, Instanzvariable, Methode

Um das Symbol „@“ zu verwenden, ohne ein Javadoc-Tag zu beginnen, kann der HTML-Zeichen-Code „@“ verwendet werden. Dies ist beispielsweise nützlich, um in einem Code-Beispiel innerhalb eines Javadoc-Kommentars Annotationen zu verwenden, die wie ein Javadoc-Tag mit einem „@“ beginnen.

Ähnliche Werkzeuge

• Doxygen
• Natural Docs
• PhpDocumentor

Weblinks

• Javadoc Homepage (englisch)
• JavaTM 2 Platform Standard Edition 6.0: API Specification – die mittels Javadoc erzeugte Original-Java-API-Dokumentation (englisch)
• MyJavadoc.net: Javadoc Search Engine - Eine Javadoc-Suchmaschine