JavaDoc
Inhaltsverzeichnis
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.
Innerhalb der JavaDoc-Kommentare können HTML-Tags zur Formatierung der späteren Ausgabe eingefügt werden.
Was sollte dokumentiert werden?
Die Beschreibung von Variablen, Methoden, Klassen und Packages 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 und wie sich der Code verhält, wenn ungültige Werte übergeben wurden, einschließlich der Fehlerbehandlung.
Für schwer zu erklärende Sachverhalten können auch Code-Beispiele im Kommentar hinterlegt werden.
Kommentar-Tags
- /** - leitet einen JavaDoc-Kommentar ein.
- */ - beendet einen JavaDoc-Kommentar.
- @param - dokumentiert ein an eine Methode übergebenes Argument.
- @return - dokumentiert 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 zu einer Klasse im Kommentartext. (siehe @see)
- 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 samt Navigation und Links.
Das prominenteste Beispiel für eine mit JavaDoc erzeugte Code-Dokumentation ist die API-Dokumentation der Java SE.
Links
- API Dokumentation (Java)
