Lernpfad:Würfelspiel in Java/Klassendokumentation mit Javadoc
Klassendokumentation mit Javadoc
JavaDoc ist ein Format, um die Dokumentation von Klassen, Attributen und Methoden direkt im Quelltext zu verfassen. Dadurch ist die Dokumentation einer Methode direkt mit ihrem Quelltext verknüpft. Hält sich ein Programmierer an die Vorgaben des Formats ergeben sich viele Vorteile:
- Klasse-Dateien lassen sich einfacher weitergeben und verstehen, da sie ihre eigene Dokumentation enthalten.
- Der eigene Quelltext wird lesbarer und lässt sich auch nach längerer Zeit nachvollziehen.
- Gängige Programmierumgebungen (wie z.B. BlueJ, IntelliJ, Visual Studio Code, Eclipse, NetBeans) erkennen die Dokumentation und zeigen sie direkt im Programm an. Zum Teil erlauben sie auch das Durchsuchen der Kommentare.
- Aus dem Quelltext lässt sich direkt eine HTML-Version der Dokumentation erstellen, die separat vom Quelltext angezeigt werden kann. Prominentestes Beispiel ist die offizielle Java API-Dokumentation.
Aufbau eines JavaDoc Kommentars
JavaDoc Kommentare nutzen die normale Java-Syntax für mehrzeilige Kommentare mit dem Zusatz, dass der Kommentar
mit zwei Sternchen statt einem eingeleitet wird (/** statt /*). Jede Zeile des Kommentars
wird zusätzlich mit einem Sternchen begonnen. Beendet wird der Kommentar mit dem normalen */.
Der Kommentar an sich folgt einer festen Struktur:
/**
* Kurze Beschreibung
* Lange Beschreibung auch über
* mehrere Zeilen. Kann auch
* <b>HTML-Elemente</b> enthalten.
*/
Nach der ausführlichen Beschreibung der Klasse oder Methode kann eine Liste von Eigenschaften folgen, die
jeweils mit einem @-Schlüsselwort beginnen.
/**
* Beispiel für JavaDoc-Eigenschaften
* @author Ngb
* @version 1.0
* @param pMenge Methoden-Parameter, der die Menge beschreibt
* @return Beschreibung des Rückgabetyps
* @see java.lang.Math#random()
*/
Es gibt viele verschiedene Eigenschaften, die zum Teil nur für Klassen oder Methoden erlaubt sind. Zum
Beispiel ergibt es wenig Sinn, die @param-Eigenschaft für die Dokumentation von Klassen
zu verwenden (da sie einen Parameter einer Methode beschreibt).
Einige wichtige Eigenschaften sind:
@author- Name des oder der Autoren. Macht i.d.R. nur Sinn bei Klassen.
- Beispiel:
@author J. Neugebauer <schule@neugebauer.cc> - Beispiel:
@author Ngb, Smr, Dop @version- Legt die Version der Klasse fest. Maximal einmal pro Klasse oder Interface verwenden. Die Version wird entweder über ein Datum festgelegt, oder über eine Versionsnummer. Für Versionsnummern gibt es keinen einheitlichen Standard, weitverbreitet ist aber das Semantic Versioning.
- Beispiel:
@version 2018-05-20 - Beispiel:
@version 1.0.1 @param- Beschreibt den Parameter einer Methode oder eines Konstruktors. Das Format der Einträge ist
@param pName Beschreibung. - Beispiel:
@param pTitel Titel des Objektes. @return- Beschreibt den Rückgabewert einer Methode. Im Gegensatz zu
@parammuss kein Name angegeben werden. - Beispiel:
@return Eine Zufallszahl zwischen 1 und 6. @see- Kann am Ende benutzt werden, um auf eine andere Methode oder Klasse zu verweisen, deren Dokumentation gegebenenfalls weiteren Aufschluss über die Funktionsweise gibt. Beispielsweise könnte eine Methode
werfen()in der KlasseWürfelauf die Methoderandom()injava.lang.Mathverweisen. - Der Verweis erfolgt entweder relativ auf ein Symbol (Attribut, Methode) der aktuellen Klasse:
- Beispiel:
@see #werfen() - oder absolut auf ein Symbol einer anderen Klasse:
- Beispiel:
@see java.util.Random#nextInt(int) @link- Links funktionieren ähnlich wie
@see, werden aber nicht am Ende der Tags aufgeführt, sondern im Kommentartext verwendet. Dazu müssen sie in geschweiften Klammern stehen. Links können neben Symbolen auch auf Webseiten verweisen. - Beispiel:
Link zum Wiki: {@link https://ngb.schule/wiki} - Beispiel:
Link zur Scanner-Klasse: {@link java.util.Scanner}
Einige Eigenschaften wie @see oder @link können auch innerhalb des Langkommentars eingefügt werden. Dann müssen sie innerhalb von geschweiften Klammern stehen. Um zum Beispiel im Kommentar einen Link zur Klasse java.lang.Math einzufügen, schreibt man {@link java.lang.Math}.
Beispiel einer Klasse mit Dokumentation
import java.util.Random;
/**
* Eine Klasse um Zufallszahlen zu "würfeln".
* Die Klasse generiert ganze
* <a href="https://de.wikipedia.org/wiki/Pseudozufall">Pseudozufallszahlen</a>
* von 1 bis zu einem vorher festgelegten Maximum. Um einen normalen
* sechseitigen Würfel zu erzeugen benutzt man:
* <pre>
* Wuerfel w = new Wuerfel(6);
* </pre>
* Die ZUfallszahlen werden mit Hilfe von {@link java.util.Random} generiert.
*
* @author J. Neugebauer <schule@neugebauer.cc>
* @version 2018-05-05
*/
public class Wuerfel {
private int seiten;
private Random zufall;
/**
* Konstruktor für Objekte der Klasse Wuerfel.
* @param pSeiten Anzahl der Seiten des Würfels.
*/
public Wuerfel( int pSeiten ) {
seiten = pSeiten;
zufall = new Random();
}
/**
* "Wirft" den Würfel
* Es wird eine Zufallszahl zwischen 1 und dem vorher festgelegten
* Maximum (einschließlich) generiert.
* @return Eine Ganzzahl von 1 bis zum Maximum
* @see java.util.Random#nextInt(int)
*/
public int werfen() {
// nextInt(int) generiert eine Zufallszahl n mit 0 <= n < 6
return zufall.nextInt(seiten)+1;
}
}
HTML-Dokumentation und Javadoc in BlueJ
JavaDoc ist nicht nur ein Format für Kommentare, sondern auch ein Programm, dass einen Ordner mit Quelltexten nimmt, und aus den Inhalten eine HTML-Seite generiert, die die Dokumentation der Klassen darstellt. Die Dokumentation zur Wuerfel Klasse oben sieht dann etwa so aus:
BlueJ integriert die JavaDoc-Dokumentation direkt in das Editor-Fenster. Oben rechts kann zwischen den Ansichten Quelltext und Dokumentation umgeschaltet werden. Die Dokumentation wird dann direkt aus den Kommentaren im Quelltext generiert und angezeigt.
