JavaDoc
JavaDoc ist ein kleines Werkzeug aus dem JDK, mit dem sich aus speziellen Kommentaren im Quellcode eines Java-Programmes Dokumentationstexte im HTML-Format generieren lassen.
Dabei werden die Kommentar-Tags direkt über der zu beschreibenden Klasse notiert.
Die Beschreibung von Variablen, Methoden und Klassen sollte nicht aus einer Funktionsbeschreibung bestehen, sondern vielmehr aus der Beschreibung des Einsatzzweckes oder der Wirkung des dokumentierten Codes. Außerdem aus einer Beschreibung von erwarteten Argumenten und Rückgabewerten.
Innerhalb der JavaDoc-Kommentare können HTML-Tags zur Formatierung der späteren Ausgabe eingefügt werden.
Kommentar-Tags
- /** - leitet einen JavaDoc-Kommentar ein.
- */ - beendet einen JavaDoc-Kommentar.
- @param - dokumentiert ein an eine Methode übergebenes Argument.
- @return - dokumentier den Rückgabewert einer Methode.
- @see - dient zum Verweisen (Link) auf einen weiterführenden Text in einer (anderen) Dokumentation (Bsp.: @see javax.swing.JButton#setText() )
- @since - dient zur Hervorhebung der Einführung in den Code, also seit wann (z.B. Versionsnummer) ein bestimmtes Feature verfügbar ist.
- @deprecated - dient zum Kennzeichnen veralteter Methode, die nicht mehr eingesetzt werden sollten. Siehe auch: deprecated.
- @throws - dient zur Angabe von checked (geprüften) Exceptions.
- @author - dient zur Angabe des Autors einer Klasse oder Methode.
- @version - dient zur Angabe der Version einer Klasse oder Methode.
- @link - dient zur Angabe eines Hyperlinks im Kommentartext.
- dient zum Formatieren von Code-Beispielen innerhalb der JavaDoc. (Bsp.:BeispielCode bc = new BeispielCode();
Beispiel
Ein kleines Beispiel soll die Dokumentation einer Methode verdeutlichen:
<code=java>/**
* Gibt ein Image-Objekt zurück, das auf den Bildschirm gezeichnet werden kann.
* Das URL-Argument muss einen absoluten {@link URL} spezifizieren.
* Das Argument name spezifiziert dabei den relativen Teil zu der URL.
*
* Die Methode kehrt sofort zurück, unabhängig davon, ob das Image existiert.
* Wenn dieses Applet das Zeichnen auf den Bildschirm anstößt, werden die
* Daten geladen.
*
* @param url eine absolute URL, die den Basis-Speicherort des Bildes angibt.
* @param name der Speicherort des Bildes, relativ zur URL
* @return das Bild an der spezifizierten URL
* @see Image
*/
public Image getImage(URL url, String name) {
try {
return getImage(new URL(url, name));
}
catch (MalformedURLException e) {
return null;
}
}</code=java>
JavaDoc Werkzeug
Die Erzeugung der Dokumentation aus den JavaDoc-Kommentaren kann nun mit folgendem Befehl in der Kommandozeile des Betriebssystems ausgelöst werden:
javadoc Klassenname.java
Dabei erzeugt JavaDoc entsprechend der im Quelltext hinterlegten Dokumentation Webseiten mit dem Dokumentationsinhalt mit Navigation und Links.
Das prominenteste Beispiel für eine mit JavaDoc erzeugte Code-Dokumentation ist die API-Dokumentation der Java SE.
