Upload
others
View
58
Download
0
Embed Size (px)
Citation preview
AutomaticDocumentationGeneration
WithJAVADOC
Markus Fleischauer, Kai DührkopLehrstuhl für Bioinformatik6. November, 2017
Javadoc
● Ist Teil des JDK (und damit defacto Standard für die Java Welt)
● Erzeugt eine HTML Dokumentation aus eurem Sourcecode und den darin enthaltenen javadoc comments
● Lässt sich via Gradle ausführen
Javadoc Comments
Jedes Javadoc beginnt mit einem /**
Javadoc Comments
Kommentar zur Beschreibung einer Klasse/Interface
Javadoc Comments
Der erste Satz, endend mit einem Punkt, gefolgt von einem Whitespace ist die Kurzbeschreibung
Javadoc Comments
Zur Formatierung darf beliebiges HTML verwendet werden
Javadoc Comments
Weitere Tags am Ende des Kommentars für Metainformationen
Javadoc Comments
Spezielle “Inline Tags”, von {} umschlossen und mit einem @ beginnend, um Links etc. zu generieren
Klassendokumentation
● Dokumentation beginnt NACH package Angabe und Import-Befehlen
● Fängt mit Kurzbeschreibung (ein Satz!) der Klasse an● Daraufhin folgt die detailierte Beschreibung● Immer gut: Codebeispiele für die Anwendung der Klasse.
Codebeispiele können mit <pre> HTML Tags umschlossen werden
Methodendokumentation
● Kurzbeschreibung und (optional) Detailbeschreibung● Daraufhin für jeden Parameter eine Zeile mit @param Tag● Eine Zeile mit @return Tag für den Rückgabewert● Eventuelle Exceptions die geworfen werden können in
einem @throws Tag erwähnt werden● Achtung: Bestimmte HTML Zeichen wie <, > müssen
escaped werden
Symbolreferenzen
● {@link package.Klasse#methode(typ,typ)} erzeugt einen Link auf die jeweilige Methode
Was muss alles dokumentiert werden?
● Öffentliche Variablen, Konstanten, Methoden, Konstruktoren, Klassen
● Möglichst auch Methoden/Felder die protected sind
Was gehört in die Dokumentation rein?
● Bedeutung der Parameter und Rückgabewerte● Spezialfälle (darf ein Parameter null sein?)● Exceptions die geworfen werden
Was gehört NICHT in die Dokumentation?
● Trivialkommentare
FALSCH
Was gehört NICHT in die Dokumentation?
● Trivialkommentare
RICHTIG
Umsetzung in der IDE
Umsetzung in der IDE
● STRG+Q zeigt Dokumentation für Symbol an