Dokumentation mit javadoc - KIT

Programmieren I
Dokumentation mit Javadoc
Heusch 10.4
Ratz 4.1.1
Institut für Angewandte Informatik
KIT – Die Forschungsuniversität in der Helmholtz-Gemeinschaft
www.kit.edu
Automatische Dokumentation
Java bietet standardmäßig das Dokumentationssystem
Javadoc. Dieses unterstützt die automatische Erstellung
der Dokumentation ganzer Programmsysteme.
Für die Dokumentation
werden Kommentare
im Code verwendet.
(-> Javadoc kann nur
dokumentieren, was im
Code auch kommentiert
wurde!)
Die Kommentare werden
durch Tags (KommentarBefehle, @-Elemente) angereichert.
2
W. Geiger, W. Süß, T. Schlachter, C. Schmitt
Institut für Angewandte Informatik
Kommentar-Typen
Einzeilige Kommentare (bis zum Zeilenende)
// Ich bin ein einzeiliger Kommentar
System.out.println("Hello World"); // Ausgabe einer Nachricht
Mehrzeilige Kommentare ("Blockkommentare")
/* String fractionString = Utils.inputString(System.in);
* int pos = fractionString.indexOf("/")
*/
/* Die Methode implementiert das Kürzen eines
* Bruchs mittels GGT-Algorithmus */
Kommentare für die automatischen Programmdokumentation mit Javadoc
/** Programmdokumentation zur Klasse Fraction */
public class Fraction {
/** Doku zum Attribut numerator */
public int numerator;
/** Doku zur Methode add(Fraction) */
public Fraction add(Fraction f) { /*...*/ }
}
3
W. Geiger, W. Süß, T. Schlachter, C. Schmitt
Institut für Angewandte Informatik
Javadoc-Input/-Output
Aus Kommentaren, die mit /** beginnen und mit */
enden ("Javadoc-Kommentare"), erzeugt Javadoc
automatisch eine Dokumentation im HTML-Format.
Ein Beispiel für eine von Javadoc erstellte Dokumentation
ist die Dokumentation der Java-API (Java Application
programming interface), d.h. die Online-Dokumentation
der Java-Klassen-Bibliotheken unter
http://docs.oracle.com/javase/8/docs/api/
4
W. Geiger, W. Süß, T. Schlachter, C. Schmitt
Institut für Angewandte Informatik
(z.B. http://docs.oracle.com/javase/8/docs/api/)
interfaces and classes
packages
Javadoc-Output
5
class details
W. Geiger, W. Süß, T. Schlachter, C. Schmitt
Institut für Angewandte Informatik
Zugang zur API-Dokumentation
Über Browser: http://docs.oracle.com/javase/8/docs/api/
Über die IDE. Z.B. in NetBeans:
Klasse oder Methode markieren > Rechtsklick > Show
Javadoc
Die API-Dokumentation kann auch auf den eigenen
Rechner heruntergeladen werden.
Anleitung hierzu für NetBeans: siehe
http://wiki.netbeans.org/FaqJavaDoc > 1 Adding the JDK
Javadoc to the NetBeans IDE
6
W. Geiger, W. Süß, T. Schlachter, C. Schmitt
Institut für Angewandte Informatik
Einfaches eigenes Beispiel für die Kommentierung
einer Klasse und einer Methode für Javadoc
/**
* Hello-World-Programm in Java.
* Dies ist ein Javadoc-Kommentar
*
* @author John Doe
* @version 0.9
* @since 0.1
*/
public class HelloWorld {
/**
* Hauptprogramm
*
* @param args Kommandozeilen-Parameter
*/
public static void main(String[] args) {
System.out.println("Hello World!");
}
}
7
W. Geiger, W. Süß, T. Schlachter, C. Schmitt
Institut für Angewandte Informatik
Die wichtigsten @-Elemente (Kommentar-Befehle)
@author – Wer hat das verbockt?
@version – Version der Klasse/Methode/Programms/...
@param – Welche Parameter werden übergeben
@param Parametername Beschreibung
@return – Was ist die Bedeutung des Rückgabewertes
@return Beschreibung
@throws, @exception – Welche Ausnahmen sind möglich
@throws Ausnahme-Klassenname Beschreibung
@see – ermöglicht eine Referenz auf die Dokumentation
anderer Klassen und Methoden
Beispiel
@see Klassenname
@see Klassenname#Methodenname
8
W. Geiger, W. Süß, T. Schlachter, C. Schmitt
/**
* @see java.lang.Object
*/
Institut für Angewandte Informatik
Weitere @-Elemente
@deprecated – um veraltete/herabgesetzte Methoden zu
markieren
@deprecated As of JDK 1.1, replaced by
{@link #setBounds(int,int,int,int)}
@since – wenn ein Feld oder eine Methode ab einer
bestimmten Version verfügbar ist
@since 1.5
@serial, @serialData, @serialField – für serialisierbare
Attribute
{@value} – zum Anzeigen des Wertes eines statischen
Feldes
9
W. Geiger, W. Süß, T. Schlachter, C. Schmitt
Institut für Angewandte Informatik
Integration von HTML-Code
In die Kommentare kann auch beliebiger HTML-Code
integriert werden (HTML-Tags, embedded HTML)
Beispiel (präformatierter Textabschnitt):
/**
* <pre>
* System.out.println(new Date());
* </pre>
*/
public static void main(String[] args) {
System.out.println(new Date());
}
Vollständige Beschreibung von Javadoc:
http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/index.html
10
W. Geiger, W. Süß, T. Schlachter, C. Schmitt
Institut für Angewandte Informatik
Aufruf von Javadoc zur Erstellung der
Dokumentation (1) – über Kommandozeile
Das Javadoc-Tool ist Bestandteil des JDK.
Zur Generierung der Doku über Konsolenfenster: a) ins Source-CodeVerzeichnis der Klasse(n) wechseln, javadoc *.java eingeben (bzw.
für nur eine Klasse deren Namen statt "*") oder b) ins Projektverzeichnis
> javadoc *.java # im Sourcecode-Verzeichnis
> javadoc -d doc -sourcepath src -subpackages de
oder
# im Projektverzeichnis
Zum Ansehen der erzeugten
Dokumentation die Datei
index.html in den
Browser laden. Diese liegt:
- im 1. Fall im Source-CodeVerzeichnis
- im 2. Fall im Unterverzeichnis doc des
Projektverzeichnisses
11
W. Geiger, W. Süß, T. Schlachter, C. Schmitt
Institut für Angewandte Informatik
Aufruf von Javadoc (2) – NetBeans
Entwicklungsumgebungen stellen Funktionalität zur
Generierung von Javadoc bereit
Run >
Generate Javadoc
Im Projekt-Verzeichnis wird dann ein Verzeichnis
dist / javadoc erzeugt, und der Browser wird gestartet.
12
W. Geiger, W. Süß, T. Schlachter, C. Schmitt
Institut für Angewandte Informatik
Aufruf von Javadoc (3) – Eclipse
Project > Generate Javadoc…
13
W. Geiger, W. Süß, T. Schlachter, C. Schmitt
Institut für Angewandte Informatik
Ergebnis für die obige Klasse HelloWorld
14
W. Geiger, W. Süß, T. Schlachter, C. Schmitt
Institut für Angewandte Informatik
Umfangreicheres Beispiel
Ein etwas umfangreicheres Beispiel für die Kommentierung
einer Klasse für Javadoc:
Musterlösung zur Aufgabe "Zweidimensionaler Punkt" des
Aufgabenblatts "Klassen (1)".
Hinweise:
Javadoc erstellt standardmäßig nur für public- und
protected-Elemente eine Dokumentation.
Mit der -private Option von Javadoc kann aber auch für
private-Elemente eine Dokumentation erstellt werden.
Bei NetBeans angebbar unter: Run > Set Project
Configuration > Customize… > Documenting.
15
W. Geiger, W. Süß, T. Schlachter, C. Schmitt
Institut für Angewandte Informatik
Ergänzung: Java Code Conventions
Eine weitere Maßnahme – neben Dokumentation –
für „leichtere Verständlichkeit von Programmen“ sind
Programmierkonventionen (Code Conventions).
Für Java-Programme gibt es oft eine spezifische
Programmierkonvention der jeweiligen Firma oder
Einrichtung.
Von den Java-Entwicklern gibt es Code Conventions unter
http://www.oracle.com/technetwork/java/codeconventions-150003.pdf
Programmierkonventionen sind zu einem gewissen Grad
willkürlich („Geschmacksache“).
16
W. Geiger, W. Süß, T. Schlachter, C. Schmitt
Institut für Angewandte Informatik