Lernpfad:Würfelspiel in Java/Klassendokumentation mit Javadoc: Unterschied zwischen den Versionen
Jneug (Diskussion | Beiträge) Keine Bearbeitungszusammenfassung |
Jneug (Diskussion | Beiträge) Keine Bearbeitungszusammenfassung |
||
| Zeile 49: | Zeile 49: | ||
; <code>@author</code> | ; <code>@author</code> | ||
: Name des oder der Autoren | : Name des oder der Autoren. Macht i.d.R. nur Sinn bei Klassen. | ||
; <code>@version</code> | ; <code>@version</code> | ||
: | : | ||
| Zeile 62: | Zeile 62: | ||
{{Hint:Start}} | {{Hint:Start}} | ||
Eigenschaften wie <code>@see</code> können auch innerhalb des Langkommentars eingefügt werden. Dann müssen sie | 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>. | ||
{{Hint:End}} | {{Hint:End}} | ||
Version vom 13. Mai 2018, 17:26 Uhr
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, 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
*/
Es gibt viele Verschiedene Eigenschaften, die zum Teil nur für Klassen oder Methoden erlaubt sind. Zum
Beispiel macht es keinen 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.
@version@param@return@see@link
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
/**
* Eine Klasse, die einen Motorroller repräsentiert.
* @author J. Neugebauer
* @version 2018-05-05
*/
public class Motorroller {
private int tankfuellung = 0;
/**
* Tankt den Roller auf.
* @param pMenge Die zu tankende Menge in Litern.
*/
public void tanken( int pMenge ) {
tankfuellung = tankfuellung + pMenge;
}
/**
* Getter für den Tankinhalt.
* @return Der aktuelle Tankinhalt in Litern.
*/
public int getTankfuellung() {
return tankfuellung;
}
}