automatic documentation generation with...automatic documentation generation with javadoc markus...
TRANSCRIPT
![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](https://reader030.vdocuments.mx/reader030/viewer/2022040101/5f3215a504477a6cb03f2371/html5/thumbnails/1.jpg)
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](https://reader030.vdocuments.mx/reader030/viewer/2022040101/5f3215a504477a6cb03f2371/html5/thumbnails/2.jpg)
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](https://reader030.vdocuments.mx/reader030/viewer/2022040101/5f3215a504477a6cb03f2371/html5/thumbnails/3.jpg)
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](https://reader030.vdocuments.mx/reader030/viewer/2022040101/5f3215a504477a6cb03f2371/html5/thumbnails/4.jpg)
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](https://reader030.vdocuments.mx/reader030/viewer/2022040101/5f3215a504477a6cb03f2371/html5/thumbnails/5.jpg)
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](https://reader030.vdocuments.mx/reader030/viewer/2022040101/5f3215a504477a6cb03f2371/html5/thumbnails/6.jpg)
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](https://reader030.vdocuments.mx/reader030/viewer/2022040101/5f3215a504477a6cb03f2371/html5/thumbnails/7.jpg)
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](https://reader030.vdocuments.mx/reader030/viewer/2022040101/5f3215a504477a6cb03f2371/html5/thumbnails/8.jpg)
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](https://reader030.vdocuments.mx/reader030/viewer/2022040101/5f3215a504477a6cb03f2371/html5/thumbnails/9.jpg)
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](https://reader030.vdocuments.mx/reader030/viewer/2022040101/5f3215a504477a6cb03f2371/html5/thumbnails/10.jpg)
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](https://reader030.vdocuments.mx/reader030/viewer/2022040101/5f3215a504477a6cb03f2371/html5/thumbnails/11.jpg)
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](https://reader030.vdocuments.mx/reader030/viewer/2022040101/5f3215a504477a6cb03f2371/html5/thumbnails/12.jpg)
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](https://reader030.vdocuments.mx/reader030/viewer/2022040101/5f3215a504477a6cb03f2371/html5/thumbnails/13.jpg)
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](https://reader030.vdocuments.mx/reader030/viewer/2022040101/5f3215a504477a6cb03f2371/html5/thumbnails/14.jpg)
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](https://reader030.vdocuments.mx/reader030/viewer/2022040101/5f3215a504477a6cb03f2371/html5/thumbnails/15.jpg)
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](https://reader030.vdocuments.mx/reader030/viewer/2022040101/5f3215a504477a6cb03f2371/html5/thumbnails/16.jpg)
![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](https://reader030.vdocuments.mx/reader030/viewer/2022040101/5f3215a504477a6cb03f2371/html5/thumbnails/17.jpg)
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](https://reader030.vdocuments.mx/reader030/viewer/2022040101/5f3215a504477a6cb03f2371/html5/thumbnails/18.jpg)