18
Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017

Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017 Javadoc Ist

  • Upload
    others

  • View
    58

  • Download
    0

Embed Size (px)

Citation preview

Page 1: Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017 Javadoc Ist

AutomaticDocumentationGeneration

WithJAVADOC

Markus Fleischauer, Kai DührkopLehrstuhl für Bioinformatik6. November, 2017

Page 2: Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017 Javadoc Ist

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

Page 3: Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017 Javadoc Ist

Javadoc Comments

Jedes Javadoc beginnt mit einem /**

Page 4: Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017 Javadoc Ist

Javadoc Comments

Kommentar zur Beschreibung einer Klasse/Interface

Page 5: Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017 Javadoc Ist

Javadoc Comments

Der erste Satz, endend mit einem Punkt, gefolgt von einem Whitespace ist die Kurzbeschreibung

Page 6: Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017 Javadoc Ist

Javadoc Comments

Zur Formatierung darf beliebiges HTML verwendet werden

Page 7: Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017 Javadoc Ist

Javadoc Comments

Weitere Tags am Ende des Kommentars für Metainformationen

Page 8: Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017 Javadoc Ist

Javadoc Comments

Spezielle “Inline Tags”, von {} umschlossen und mit einem @ beginnend, um Links etc. zu generieren

Page 9: Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017 Javadoc Ist

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

Page 10: Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017 Javadoc Ist

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

Page 11: Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017 Javadoc Ist

Symbolreferenzen

● {@link package.Klasse#methode(typ,typ)} erzeugt einen Link auf die jeweilige Methode

Page 12: Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017 Javadoc Ist

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

Page 13: Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017 Javadoc Ist

Was gehört NICHT in die Dokumentation?

● Trivialkommentare

FALSCH

Page 14: Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017 Javadoc Ist

Was gehört NICHT in die Dokumentation?

● Trivialkommentare

RICHTIG

Page 15: Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017 Javadoc Ist

Umsetzung in der IDE

Page 16: Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017 Javadoc Ist
Page 17: Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017 Javadoc Ist

Umsetzung in der IDE

● STRG+Q zeigt Dokumentation für Symbol an

Page 18: Automatic Documentation Generation With...Automatic Documentation Generation With JAVADOC Markus Fleischauer, Kai Dührkop Lehrstuhl für Bioinformatik 6. November, 2017 Javadoc Ist