Javadoc
aus Wikipedia, der freien Enzyklopädie
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.
Inhaltsverzeichnis |
[Bearbeiten] 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.
[Bearbeiten] 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!"); } }
[Bearbeiten] 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.
[Bearbeiten] Übersicht der Javadoc-Tags
| Tag & Parameter | Ausgabe | Verwendung in | seit |
|---|---|---|---|
@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 | 1.4.0 |
{@link reference} |
Link zu einem anderen Symbol. | Klasse, Interface, Instanzvariable, Methode | |
{@linkPlain reference} |
Der Link wird in Standardtext statt in Quelltextzeichensatz angezeigt. | Klasse, Interface, Instanzvariable, Methode | 1.4.0 |
{@value} |
Gibt den Wert eines konstanten Feldes zurück. | Statisches Feld | 1.4.0 |
{@code} |
Formatiert Text buchstabengetreu mit dem Quelltextzeichensatz (entsprechend <code>) und unterdrückt die Interpretierung von beinhalteten HTML oder Javadoc-Tags. | Klasse, Interface, Instanzvariable, Methode | 5.0 |
{@literal} |
Kennzeichnet buchstabengetreuen Text und unterdrückt die Interpretierung von beinhalteten HTML oder Javadoc-Tags. | Klasse, Interface, Instanzvariable, Methode | 5.0 |
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.
[Bearbeiten] Ähnliche Werkzeuge
[Bearbeiten] 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
