Javadoc

Javadoc ist ein Software-Dokumentationswerkzeug, das aus Java-Quelltexten automatisch HTML-Dokumentationsdateien erstellt. Für zusätzliche Informationen können spezielle Kommentare im Quelltext eingefügt werden.

Kommentare können dabei für Interfaces, Klassen, Methoden und Felder über spezielle Doclet-Tags definiert werden. Javadoc wurde ebenso wie Java von Sun Microsystems entwickelt und ist Bestandteil des Java 2 Software Development Kits (J2SDK).

Nach dem Vorbild Javadocs entwickelte Microsoft XmlDoc für seine .NET-Plattform.

Anwendungsgebiet

Java ist eine objektorientierte Programmiersprache. Die Kapselung und das Geheimnisprinzip werden als zentrale Elemente objektorientierten Programmierens angesehen, insbesondere in Java. Daraus folgt, dass zur Verwendung eines Symbols, z.B. einer Klasse oder einer Methode, seine öffentliche Schnittstelle und seine Spezifikation herangezogen werden sollten. Sich vor der Verwendung Kenntnisse über die interne Funktionsweise zu verschaffen, verstößt gegen das Geheimnisprinzip und macht außerdem unter Umständen von Änderungen in der Implementierung abhängig. Daher ist es notwendig, die Schnittstelle zu spezifizieren und dokumentieren. Das ist das Haupteinsatzgebiet von Javadoc.

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!");
    }

} // class Hello

Beispiel-Ausgabe

Auch die Java-API-Dokumentation wurde mit Hilfe von Javadoc erstellt. Sie ist meist die erste Javadoc-Dokumentation, mit der ein Java-Programmierer konfrontiert wird. Sie ist zu finden unter [1].

Ü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 das Feature existiert.	Klasse, Interface
@see reference	Erzeugt einen Link auf ein anderes Element der Dokumentation. Z.B. @see java.util.Hashtable	Klasse, Interface, Instanzvariable, Methode
@param name description	Parameterbeschreibung einer Methode.	Methode
@return description	Beschreibung des Returnwerts einer Methode.	Methode
@exception 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.	Methode

Siehe auch

• Doxygen, ein Dokumentationswerkzeug für diverse Programmiersprachen, auch Java

Weblinks

• Javadoc Homepage (engl.)
• Javadoc und Doclets (Vortrag)