Infoportal
Inhaltsverzeichnis
JavaDoc
JavaDoc ist ein Software-Dokumentationswerkzeug, welches das automatische Erstellen von HTML-Dokumentationsseiten ermöglicht. Es wurde von Sun Microsystems entwickelt und ist Bestandteil des Java Developer Kits.
Funktionsweise
JavaDoc parst den Java-Quellcode und generiert daraus automatisch HTML-Dokumente. Dazu sind jedoch spezielle JavaDoc-Kommentare notwendig (beginnend mit /**). Die Position dieser Kommentare gibt wie gewohnt an zu was der Kommentar gehört: immer zum nachfolgenden Block. Im Kommentar können spezielle JavaDoc-Tags verwendet werden.
JavaDoc-Tags
| Tag & Parameter | Beschreibung | Verwendbar in |
|---|---|---|
@author name | Beschreibt den Autor | Klasse, Interface |
@version version | Erzeugt einen Versionseintrag. Darf max. einmal pro Klasse oder Interface verwendet werden! | Klasse, Interface |
@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 Rückgabewertes einer Methode | Methode |
@deprecated description | Beschreibt eine veraltete Methode, die nicht mehr verwendet werden sollte. Sollte immer mit der @Deprecated-Annotation verwendet werden! | Methode |
@exception classname description | Beschreibung einer Exception, die von dieser Methode geworfen werden kann. | Methode |
@throws classname description |
||
@since jdk-version | Seit wann die Funktionalität existiert. | Klasse, Interface, Instanzvariable, Method |
{@inheritDoc} | Kopiert die Beschreibung aus der überschriebenen Methode. | Überschreibende Methode |
{@link reference} | Link zu einem anderen Symbol. | Klasse, Interface, Instanzvariable, Methode |
{@linkPlain reference} | Link zu einem anderen Symbol. Der Link wird jedoch als Standardtext angezeigt. | Klasse, Interface, Instanzvariable, Methode |
{@value} | Gibt den Wert eines konstanten Feldes zurück. | Statisches Feld |
{@code} | Formatiert Text buchstabengetreu mit dem Quelltextzeichensatz 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 |
Beispiele
Hello-World-Beispiel
/** * Ein einfaches Hello-World-Beispiel in Java * mit Javadoc-Kommentaren. Wieviel Text in * so einem Kommentar steht, ist egal. * * @author Martin Züger * @version 0.1 */ public class HelloWorld { /** * Hauptmethode: Wird beim Starten aufgerufen * * @param args Kommandozeilenparameter */ public static void main(String[] args) { System.out.println("Hello NTB!"); } }
Dokumentation generieren
Die Dokumentation kann mithilfe des Kommandozeilentools javadoc erstellt werden. Dieses verfügt über eine relativ grosse Anzahl möglicher Parameter.
Die einfachste Art die Dokumentation zu erstellen ist, javadoc von Hand ohne Parameter aufzurufen:
javadoc PACKAGE
Damit wird vom Paket PACKAGE (welches im aktuellen Verzeichnis liegen muss) eine Dokumentation erstellt und ebenfalls im aktuellen Verzeichnis abgelegt.
Praktischer ist es jedoch, wenn man das Verzeichnis für die Java-Quellen und das Ausgabeverzeichnis angeben kann. Zudem ist es mühsam, wenn immer alle Pakete einzeln angegeben werden müssen. Abhilfe schaffen die beiden Parameter -d und -sourcepath sowie eine Datei mit einer Liste aller Pakete, für die eine Dokumentation benötigt wird. Dies sieht dann folgendermassen aus:
javadoc -sourcepath /java/jdk/src/share/classes -d /java/jdk/build/api @packagelist
Dabei muss im aktuellen Verzeichnis eine Datei mit dem Namen packagelist existieren, die alle gewünschten Pakete (durch Zeilenumbrüche getrennt) beinhaltet.
Einfügen: Javadoc mit Ant und Make erstellen!