Quelltext der Seite Lernpfad:Würfelspiel in Java/Klassendokumentation mit Javadoc

{{Navigation}}

== 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|link}}, {{IntelliJ|link}}, {{VSCode|link}}, {{Eclipse|link}}, {{NetBeans|link}}) 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 [https://link.ngb.schule/javaapi 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 (<code>/**</code> statt <code>/*</code>). Jede Zeile des Kommentars
wird zusätzlich mit einem Sternchen begonnen. Beendet wird der Kommentar mit dem normalen <code>*/</code>.

Der Kommentar an sich folgt einer festen Struktur:

<syntaxhighlight lang="java" line="1">
/**
 * Kurze Beschreibung
 * Lange Beschreibung auch über
 * mehrere Zeilen. Kann auch 
 * <b>HTML-Elemente</b> enthalten.
 */
</syntaxhighlight>

Nach der ausführlichen Beschreibung der Klasse oder Methode kann eine Liste von Eigenschaften folgen, die
jeweils mit einem <code>@</code>-Schlüsselwort beginnen.

<syntaxhighlight lang="java" line="1">
/**
 * 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()
 */
</syntaxhighlight>

Es gibt viele verschiedene Eigenschaften, die zum Teil nur für Klassen oder Methoden erlaubt sind. Zum 
Beispiel ergibt es wenig Sinn, die <code>@param</code>-Eigenschaft für die Dokumentation von Klassen
zu verwenden (da sie einen Parameter einer Methode beschreibt).

Einige wichtige Eigenschaften sind:

; <code>@author</code>
: Name des oder der Autoren. Macht i.d.R. nur Sinn bei Klassen.
: Beispiel: <code>@author J. Neugebauer <schule@neugebauer.cc></code>
: Beispiel: <code>@author Ngb, Smr, Dop</code>
; <code>@version</code>
: 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 [https://semver.org Semantic Versioning].
: Beispiel: <code>@version 2018-05-20</code>
: Beispiel: <code>@version 1.0.1</code>
; <code>@param</code>
: Beschreibt den Parameter einer Methode oder eines Konstruktors. Das Format der Einträge ist <code>@param ''pName'' ''Beschreibung''</code>.
: Beispiel: <code>@param pTitel Titel des Objektes.</code>
; <code>@return</code>
: Beschreibt den Rückgabewert einer Methode. Im Gegensatz zu <code>@param</code> muss kein Name angegeben werden.
: Beispiel: <code>@return Eine Zufallszahl zwischen 1 und 6.</code>
; <code>@see</code>
: 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 <code>werfen()</code> in der Klasse <code>Würfel</code> auf die Methode <code>random()</code> in <code>java.lang.Math</code> verweisen.
: Der Verweis erfolgt entweder relativ auf ein ''Symbol'' (Attribut, Methode) der aktuellen Klasse:
: Beispiel: <code>@see #werfen()</code>
: oder absolut auf ein Symbol einer anderen Klasse:
: Beispiel: <code>@see java.util.Random#nextInt(int)</code>
; <code>@link</code>
: Links funktionieren ähnlich wie <code>@see</code>, 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: <code>Link zum Wiki: {@link https://ngb.schule/wiki}</code>
: Beispiel: <code>Link zur Scanner-Klasse: {@link java.util.Scanner}</code>

{{Info:Start}}
Einige Eigenschaften wie <code>@see</code> oder <code>@link</code> 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 <code>java.lang.Math</code> einzufügen, schreibt man <code>{@link java.lang.Math}</code>.
{{Info:End}}

== Beispiel einer Klasse mit Dokumentation ==
<syntaxhighlight lang="java" line="1">
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;
	}
}
</syntaxhighlight>

== 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 <code>Wuerfel</code> Klasse oben sieht dann etwa so aus:

[[Datei:BlueJ Javadoc.jpg|thumb|center|Beispiel einer Javadoc-Dokumentation in BlueJ.]]

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.

[[Datei:BlueJ Editor.jpg|480px|center|BlueJ Editor-Fenster.]]

== Weitere Informationen ==

* https://www.home.hs-karlsruhe.de/~pach0003/labor_informatik_1/05_Javadoc.pdf
* http://openbook.rheinwerk-verlag.de/javainsel9/javainsel_05_014.htm#t2t31
* [[wikipedia:Javadoc]]