Mag. iur. Dr. techn. Michael Sonntag Softwareentwicklung Dokumentation mit JavaDoc E-Mail: sonntag@fim.uni-linz.ac.at http://www.fim.uni-linz.ac.at/staff/sonntag.htm Institut für Informationsverarbeitung und Mikroprozessortechnik (FIM) Johannes Kepler Universität Linz, Österreich Michael Sonntag 2004
??? Fragen? Bitte gleich stellen!??? Michael Sonntag 2004
Dokumentation Dokumentation ist ein essentieller Teil der Programmierung Ohne Dokumentation kann niemand anderer ihren Code verstehen, und auch sie selbst können ihren Code später nicht mehr verstehen! Dokumentation: Entwurfsdokumente (Notizen beim Entwurf, etc.) Diagramme (Klassen, Kommunikation, etc.) Pflichtenheft (=Offizielle Spezifikation, relativ grob) Spezifikation (interne Details genau festgelegt) Kommentare (im Code)... Michael Sonntag Dokumentation mit JavaDoc 3
Dokumentation Allgemeines Dokumentation/Kommentare ist manchmal in anderer Sprache als die benutzerschnittstellen-sprache Auf eine Sprache einigen, damit nicht innerhalb der Dokumentation noch gewechselt wird! Lieber zu viel Dokumentation, als später vergeblich suchen! Dokumentieren, was nicht im Code steht, sondern was man sich gedacht hat, als der Code geschrieben wurde Insbesondere Auslassungen!» Warum wurde dieser Sonderfall nicht berücksichtigt?» Was könnte man noch machen, wird aber nicht gebraucht? Warum? Insbesondere Algorithmen» Welcher Algorithmus wird verwendet (Name)?» Warum gerade dieser? Michael Sonntag Dokumentation mit JavaDoc 4
Dokumentation Java In Java kann ein Teil der Dokumentation direkt im Code geschrieben werden Anschließend werden die Informationen extrahiert und schön formatiert, mit Verzeichnissen versehen, etc. Alles dies erfolgt komplett automatisch! Kommentiert werden kann nur der eigentliche Code Plus Schnittstellen-Spezifikation! Sowie ein kleiner Teil des Designs Aufteilung in packages Wird dies vollständig integriert und konsequent sind spätere Änderungen/Erweiterungen EXTREM viel einfacher! Vielfach reicht diese Dokumentation (zusammen mit einer allgemeinen Beschreibung) aus! Michael Sonntag Dokumentation mit JavaDoc 5
Dokumentation Was genau? (1) Dokumentiert sollte jeweils werden: Klassen/Dateien: Wozu dient diese Klasse? Was macht sie? Wie verwendet man die Klasse? Beispiele! Wie arbeitet sie intern? Hinweise für Objektorientierung (wie ableiten, was überschreiben,...) Globale Variablen: Wozu dient sie? Was steht darin? Genauer Wertebereich Michael Sonntag Dokumentation mit JavaDoc 6
Dokumentation Was genau? (2) Prozeduren/Funktionen: Wozu dient die Methode? Was macht sie? Wie verwendet man sie? Beispiele! Wie arbeitet sie intern? Seiteneffekte (z. B. Veränderungen globaler Variablen) Hinweise für Objektorientierung (wie ableiten, was überschreiben,...) Wie aufrufen? Welche Parameterwerte sind erlaubt? Was wird genau zurückgegeben? Welche Fehler können auftreten? Michael Sonntag Dokumentation mit JavaDoc 7
Dokumentation Wie? (1) Normaler Kommentar: /* */ JavaDoc-Kommentar: /** */ Muß direkt vor dem zu kommentierenden stehen! "*" auf neuen Zeilen war früher notwendig (jetzt egal) Beispiel: /** Das klassische "Hello World" Programm * @author Michael Sonntag * @version 1.0, 4.5.2003 */ public class Hello { } public static void main(string[] args) { System.out.println("Hello World\n"); } Michael Sonntag Dokumentation mit JavaDoc 8
Dokumentation Wie? (2) JavaDoc Kommentare können beliebigen HTML-Code enthalten (z. B. <strong>, <code>, <h1>,...) Siehe HTML-LVA im nächsten Semester! Der erste Satz (bis zu Punkt und folgendem Whitespace) gilt als Zusammenfassung und wird in der Übersicht dargestellt Der Rest ist nur in der Detailansicht sichtbar Kommentare können beliebig lang sein und sind sehr oft viel länger als der Code, der kommentiert wird! Siehe die API-Dokumentation von Java als Beispiel! Am Ende können noch besondere "Tags" stehen Muß am Ende sein, da sie bis zum nächsten Tag oder dem Kommentar-Ende gelten Siehe nächsten Seiten für die wichtigsten Tags Michael Sonntag Dokumentation mit JavaDoc 9
Dokumentation Wie? (3) @author Wer ist der Autor dieses Programms? Falls mehrere (z. B. spätere Änderungen), neuen Tag anhängen Beispiel: @author Michael Sonntag @version Aktuelle Versionsnummer» Entweder händisch ändern,» oder vom Versionsverwaltungsprogramm verwalten lassen Beispiel: @version 1.1 Michael Sonntag Dokumentation mit JavaDoc 10
Dokumentation Wie? (4) @see classname "#" methodname "(" {parametertype} ")" Hinweis auf eine andere Methode oder Klasse Es wird automatisch ein Hyperlink dorthin erzeugt Beispiele: @see #printtext(string)» Diese Klasse/Datei, Methode "printtext(string str)" @see java.lang.integer#parseint(string,int)» Verweist auf Methode "parseint(string s, int radix)" der Klasse Integer @see java.lang.string String-Klasse» Verweist auf die gesamte Klasse String mit dem Text "String-Klasse" @see "Handbuch Kapitel 10"» Kein Link erzeugt, es wird nur der Text ausgegeben! Links werden unter der Überschrift "See also" eingefügt Michael Sonntag Dokumentation mit JavaDoc 11
Dokumentation Wie? (5) {@link}: Kann jederzeit innerhalb des Textes verwendet werden und erzeugt einen Hyperlink zum angegebenen Ziel Genau wie @see, nur werden die Links direkt im Text eingefügt Beispiel: "Use the {@link #getcomponentat(int, int) getcomponentat} method." Ergibt: "Use the <a href="component.html#getcomponentat(int, int)">getcomponentat</a> method." Notwendig um sich auf andere Klassen/Methoden zu beziehen Externe Links können direkt eingefügt werden! Beispiel: "See the <a href="http://www.project.org/">project homepage</a>." Michael Sonntag Dokumentation mit JavaDoc 12
Dokumentation Wie? (6) @param parametername Beschreibung Erklärt die Bedeutung dieses Parameters, Inhalt, Wertebereich,... Bsp.: @param val the value to convert; must be between 0 and 15 @return Beschreibung Erklärt, was die Funktion zurückgibt Bsp.: @return the numerical value of the hex digit or -1 on errors @throws AusnahmeklassenName Beschreibung Beschreibt einen Fehler, der auftreten kann Siehe Exceptions!» Nur für "checked exceptions" und solche "unchecked exceptions", die sinnvollerweise abgefangen werden können, aber nicht für implementierungsspezifische unchecked exceptions! Michael Sonntag Dokumentation mit JavaDoc 13
Richtlinien für Inhalt "Muß"-Kommentare Kommentar für jede Klasse/Datei @author @version Kommentar für jede Methode @param für jeden Parameter @return für alle Funktionen @throws für alle Ausnahmen Beschreibung für jedes Paket package.html» Eigene HTML-Datei in dem Verzeichnis des Paketes Michael Sonntag Dokumentation mit JavaDoc 14
Beispiele: Klassen-Kommentar /** Normaler Text * A class representing a window on the screen. * For example: * <pre> HTML-Tag * Window win = new Window(parent); * win.show(); * </pre> Urheber * * @author Sami Shaio * @version %I%, %G% * @see java.awt.basewindow * @see java.awt.button */ class Window extends BaseWindow {... } Versionsnummer, wird z. B. von CVS automatisch eingesetzt Hinweise auf andere Klassen mit besonderem Bezug Michael Sonntag Dokumentation mit JavaDoc 15
Beispiele: Globale Variable-Kommentar /** Kommentar * The X-coordinate of the component. * * @see #getlocation() */ int x = 1263732; Hinweis auf Methode zum Lesen, Schreiben, etc. in dieser Klasse Die eigentliche Deklaration Michael Sonntag Dokumentation mit JavaDoc 16
Beispiele: Methoden-Kommentar /** Normaler Text * Returns the character at the specified index. An index * ranges from <code>0</code> to <code>length() - 1</code>. * HTML-Tag * @param index the index of the desired character. * @return the desired character. * @exception StringIndexOutOfRangeException * if the index is not in the range <code>0</code> * to <code>length()-1</code>. * @see java.lang.character#charvalue() */ Rückgabewert public char charat(int index) {... } Parameter- Beschreibung Möglicher Fehler Hinweis auf Methode einer anderen Klasse Michael Sonntag Dokumentation mit JavaDoc 17
Erzeugen der Dokumentation (1) Tool "javadoc": Sehr viele Optionen (siehe Dokumentation)! Wichtige Optionen: "-d" pfad: Ausgabeverzeichnis "-version": Versionsnummer ausgeben "-author": Autoren-Informationen ausgeben "-windowtitle" titel: Titel für das Hauptfenster (z. B. Projektname) "-doctitle" titel: Titel in der Übersicht (z. B. Projektname)» Kann HTML-Tags enthalten» Beispiel: -doctitle "<i>software Engineering</i>" "-header" header: Kopfzeile rechts oben im Hauptfenster» Kann HTML-Tags enthalten "-footer" footer: Fußzeile rechts unten im Hauptfenster» Kann HTML-Tags enthalten "-source 1.4": Wenn assertions enthalten sind (Nur ab Version 1.4) Michael Sonntag Dokumentation mit JavaDoc 18
Erzeugen der Dokumentation (2) Komplexe Parameter, viel Aufwand: Batch-Datei schreiben Argumente in einer Datei sammeln und Spezial-Aufruf: "javadoc @argfile" erwartet alle Argumente in der Datei "argfile" Aufruf: javadoc {Argumente} Dateien/Pakete Argumente: Siehe vorige Folie! Dateien/Pakete: Welche Klassen/Dateien bzw. packages dokumentiert werden sollen Beispiel: javadoc -d api -author -version *.java Erzeugt die Dokumentation im Verzeichnis "api" (relativ zum aktuellen Verzeichnis) Integriert Autor- und Verisons-Informationen Dokumentiert alle Quellcode-Dateien (*.java) Michael Sonntag Dokumentation mit JavaDoc 19
Beispiel: Java API-Dokumentation API-Doku Michael Sonntag Dokumentation mit JavaDoc 20
Programm: Analysieren und kommentieren??? Michael Sonntag Dokumentation mit JavaDoc 21
Programm analysieren und kommentieren Schauen Sie sich das folgende Programm an und arbeiten Sie es um: Programm.java Finden Sie heraus, was es eigentlich macht Benennen Sie die Variablen um, sodaß diese sprechende und passende Namen besitzen Ändern Sie (falls es Ihnen nötig erscheint) auch die Ausgabetexte um (bzw. fügen Ausgaben ein), sodaß Benutzern die Bedienung leichter fällt Schreiben Sie Schleifen oder anderes um, wenn Ihnen scheint, daß es anders leichter verständlich ist Fügen Sie alle erforderlichen JavaDoc Kommentare ein Erzeugen Sie mit JavaDoc eine vollständige Dokumentation im Unterverzeichnis "api" Michael Sonntag Dokumentation mit JavaDoc 22
Programm analysieren und kommentieren Programm.java???.java Ergebnis Dokumentation Michael Sonntag Dokumentation mit JavaDoc 23
Programm: Analysieren und kommentieren Services-Liste Michael Sonntag Dokumentation mit JavaDoc 24
Programmanalyse Services-Liste Schauen Sie sich das folgende Programm an und arbeiten Sie es um: ServicesList.java Das Programm verwaltete eine Liste von Services (Name als String) mit dazugehörigen Portnummern Bsp,: 25 SMTP, 80 HTTP,... Fügen Sie alle erforderlichen JavaDoc Kommentare ein Versuchen Sie dazu auch herauszufinden, welche Limitierungen im Programm enthalten sind!» Hinweis: Was ist mit doppelten Werten, Fehlern,...? Dokumentieren Sie diese Limitierungen gleich mit! Erzeugen Sie mit JavaDoc eine vollständige Dokumentation im Unterverzeichnis "api" Michael Sonntag Dokumentation mit JavaDoc 25
Programmanalyse Services-Liste "Probleme" des Programms: Doppelte Namen oder Nummern werden ignoriert» Das kann gewünscht sein oder auch nicht! Keine Rückmeldung bei Fehlern» Arrays voll (Überlauf)» Doppelte Namen/Nummern» Eintrag nicht gefunden beim Löschen» Parameter-Prüfung (z. B. Port "-1" und Name ""?) Sortierung überlegen» Nach Name oder nach Portnummer? Nach beidem ist es kompliziert! Löschen bedeutet verschieben ALLER nachfolgenden Einträge!» Langsam! ServicesList2.java, API-Dokumentation Michael Sonntag Dokumentation mit JavaDoc 26
Programm: Analysieren und kommentieren Services-Liste Verbesserte Version Michael Sonntag Dokumentation mit JavaDoc 27
Programmanalyse Services-Liste - Verbessert Schauen Sie sich das Programm ServicesList.java an und werfen Sie noch einmal einen Blick auf dessen Probleme Beheben Sie die folgenden Probleme: Doppelte Namen oder Nummern werden ignoriert» Dies soll nicht erlaubt sein; Name und Nummer müssen eindeutig sein Keine Rückmeldung bei Fehlern» Arrays voll (Überlauf), Eintrag nicht gefunden beim Löschen» Parameter-Prüfung (z. B. Port "-1" und Name ""?) Sortierung überlegen» Die Daten sollen nach Portnummer aufsteigend sortiert gespeichert werden (d. h. gleich an der richtigen Stelle eintragen!) Passen Sie zum Schluß die JavaDoc-Dokumentation an und erzeugen Sie eine neue HTML-Dokumentation Michael Sonntag Dokumentation mit JavaDoc 28
Programmanalyse Services-Liste Hinweise zur Realisierung: Nehmen Sie immer nur eine Aufgabe in Angriff. Erst wenn diese abgeschlossen ist, beginnen Sie die Nächste! Halten Sie folgende Reihenfolge ein:» Bei add- und remove-methoden Rückgabewerte einführen» Parameterprüfungen einführen und entsprechende Fehler-Werte zurückgeben» Fehler-Rückgabewerte falls beim Löschen nicht gefunden» Beim Einfügen prüfen ob das Array voll ist» Prüfen auf doppeltes Einfügen: Zuerst Nummer, dann Name» Sortiertes Einfügen nach der Portnummer Fügen Sie im Hauptprogramm die entsprechenden Testfälle ein um zu überprüfen, ob Ihre Implementierung auch tatsächlich richtig funktioniert Michael Sonntag Dokumentation mit JavaDoc 29