Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus...

Preview:

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

Recommended