API-Dokumentation mit javadoc

API-Dokumentation mit javadoc
Javadoc ist ein Hilfsprogramm, das aus speziellen Kommentaren in Quelldateien automatisch eine
Dokumentation der Klassen und Schnittstellen im HTML-Format aufbaut. Es werden zunächst alle
zum Projekt gehörenden Dateien durchsucht und zu jeder Klasse eine HTML-Seite erstellt. Darin
werden alle öffentlichen Methoden und Felder der Klasse aufgeführt. Mit Hilfe der javadocKommentare kann im Quelltext die Funktion dokumentiert werden. Dieser Text erscheint dann auf
der HTML-Seite.
Für jede Methode kann man eine Beschreibung angeben. Außerdem können Angaben zu jedem
Parameter, zum Rückgabewert der Methode, zu Exceptions usw. gemacht werden.
Javadoc-Kommentare haben die Form /** ... */ im Gegensatz zur normalen Form
/* ... */. Mit Hilfe spezieller Tags wird festgelegt, welchen Teil der Text dokumentiert.
Ein javadoc-Kommentar bezieht sich immer auf das unmittelbar darunter stehende Code-Element.
Ein Kommentar vor einer Klasse dokumentiert die gesamte Klasse, während sich ein vor einer
Methode stehendes Kommentar nur auf diese bezieht.
Ausführliche Informationen zu javadoc befinden sich auf der javadoc-Homepage:
http://java.sun.com/j2se/javadoc/
Beispiel einer Funktionsdokumentation
/**
* Funktionsbeschreibung, kann über mehrere Zeilen gehen
* und <i>Formatierungen</i> im HTML-Format enthalten.
* Links wie <a href=“http://www.uni-marburg.de“>dieser</a>
* sind auch möglich. Dies ist ein javadoc-Verweis auf die
* Funktion {@link java.util.List#iterator iterator()} aus der
* Klasse java.util.List.
*
* @param
x Beschreibung des Parameters x
* @param
y Beschreibung des Parameters y
* @throws IllegalArgumentException falls Argumente ungültig
* @return Beschreibung des Rückgabewerts
* @see
"Verweistext"
* @see
java.util.List#iterator iterator()
*/
public int foo(int x, int y) throws IllegalArgumentException {
...
}
Wichtige javadoc-Tags
•
@param parameter-name beschreibung
Gibt eine Beschreibung eines Parameters an. Die Beschreibung kann sich über mehrere
Zeilen erstrecken.
•
@return beschreibung
Gibt eine Beschreibung des Rückgabewerts der Methode an. Kann mehrere Zeilen umfassen.
•
@throws klasse beschreibung
Gibt an, welche Exceptions die Methode unter welchen Umständen wirft. Für jede
Exception muss ein Tag angegeben werden.
•
@author name
Gibt den Namen des Autors der Methode an.
•
{@link package.klasse#member label}
Mit diesem Tag wird an der aktuellen Position ein Link zu einer Methode oder einem Feld
der angegebenen Klasse eingefügt. label gibt den anzuzeigenden Text an.
Innerhalb der selben Package kann auf diese Angabe verzichtet werden. Bei Verweisen auf
Methoden oder Felder der selben Klasse wird lediglich #member angegeben.
•
@see "text"
Erzeugt einen Absatz mit Querverweisen. Mit diesem Tag kann man z.B. einen
Literaturverweis oder einen Internetlink angeben.
•
@see package.klasse#member beschreibung
Hiermit wird im Absatz mit den Querverweisen ein Verweis auf eine Methode oder ein Feld
der angegebenen Klasse aufgenommen.