Programmieren I. Dokumentation mit Javadoc Heusch 10.4 Ratz Institut für Angewandte Informatik

Transkript

1 Programmieren I Dokumentation mit Javadoc Heusch 10.4 Ratz KIT Die Forschungsuniversität in der Helmholtz-Gemeinschaft

2 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 (Kommentar- angereichert. 2 W. Geiger, W. Süß, T. Schlachter, C. Schmitt

3 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 zur 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

4 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 4 W. Geiger, W. Süß, T. Schlachter, C. Schmitt

5 interfaces and classes packages Javadoc-Output (z.b. class details 5 W. Geiger, W. Süß, T. Schlachter, C. Schmitt

6 Zugang zur API-Dokumentation Über Browser: Ü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 > 1 Adding the JDK Javadoc to the NetBeans IDE 6 W. Geiger, W. Süß, T. Schlachter, C. Schmitt

7 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 * John Doe */ public class HelloWorld { /** * Hauptprogramm * args Kommandozeilen-Parameter */ public static void main(string[] args) { System.out.println("Hello World!"); } } 7 W. Geiger, W. Süß, T. Schlachter, C. Schmitt

8 Die Wer hat das Version der Welche Parameter werden Parametername Was ist die Bedeutung des Beschreibung Welche Ausnahmen sind Ausnahme-Klassenname ermöglicht eine Referenz auf die Dokumentation anderer Klassen und Methoden Klassenname#Methodenname /** java.lang.object */ 8 W. Geiger, W. Süß, T. Schlachter, C. Schmitt

9 Weitere um veraltete/herabgesetzte Methoden zu As of JDK 1.1, replaced by wenn ein Feld oder eine Methode ab einer bestimmten Version verfügbar für serialisierbare Attribute zum Anzeigen des Wertes eines statischen Feldes 9 W. Geiger, W. Süß, T. Schlachter, C. Schmitt

10 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: 10 W. Geiger, W. Süß, T. Schlachter, C. Schmitt

11 Aufruf von Javadoc zur Erstellung der Dokumentation (1) über Kommandozeile Das Javadoc-Tool ist Bestandteil des JDK. Zur Generierung der Doku über Konsolenfenster: Zunächst ins Source- Code-Verzeichnis der Klasse(n) wechseln, javadoc *.java eingeben (bzw. für nur eine Klasse deren Namen statt "*" angeben) > javadoc *.java # im Sourcecode-Verzeichnis > javadoc -d doc -sourcepath src -subpackages de # im Projektverzeichnis Zum Ansehen der erzeugten Dokumentation die Datei index.html in den Browser laden. Diese liegt: - im 1. Fall im Sourcecode-Verzeichnis - im 2. Fall im Unterverzeichnis doc des Projektverzeichnisses 11 W. Geiger, W. Süß, T. Schlachter, C. Schmitt

12 Aufruf von Javadoc (2) Eclipse Entwicklungsumgebungen stellen Funktionalität zur Generierung von Javadoc bereit Project > Generate Javadoc 12 W. Geiger, W. Süß, T. Schlachter, C. Schmitt

13 Aufruf von Javadoc (3) NetBeans Run > Generate Javadoc Im Projekt-Verzeichnis wird dann ein Verzeichnis dist / javadoc erzeugt, und der Browser wird gestartet. 13 W. Geiger, W. Süß, T. Schlachter, C. Schmitt

14 Ergebnis für die obige Klasse HelloWorld 14 W. Geiger, W. Süß, T. Schlachter, C. Schmitt

15 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: Run > Set Project Configuration > Customize > Documenting. 15 W. Geiger, W. Süß, T. Schlachter, C. Schmitt

16 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 Programmierkonventionen sind zu einem gewissen Grad willkürlich ( Geschmacksache ). 16 W. Geiger, W. Süß, T. Schlachter, C. Schmitt