Kapitel 9: JavaDoc

Liste P: Programmieren mit Java
WS 2001/2002
Prof. Dr. V. Turau
FH Wiesbaden
Kapitel 9: JavaDoc
Folie 206 : Programmdokumentation
Unentbehrlicher Bestandteil der Programmentwicklung ist eine aussagekräftige
Dokumentation
Sie erleichtert bzw. ermöglicht eine spätere Programmwartung
Die Erstellung einer Dokumentation ist bei Programmierern unbeliebt
Häufig erfolgt die Dokumentation erst nach Fertigstellung des Programmes
Viel sinnvoller ist eine in den Entwicklungsprozess integrierte Erstellung der Dokumentation
Folie 207 : Javadoc
Javadoc ist ein Werkzeug, welches die Erstellung von Dokumentationen unterstützt
Das Programm extrahiert in den Programmcode eingefügte Kommentare und generiert daraus
HTML-Dokumente
Die Darstellung mittels eines Hypertextes hat viele Vorteile:
Bessere Lesbarkeit
Textbasierte Suche
Navigation entlang Programmstrukturen durch Hyperlinks
Alternativ können andere Formate erstellt werden: WinHelp, druckbare Varianten wie PDF
Folie 208 : Javadoc
Eine automatische Generierung der Dokumentation hat viele Vorteile:
Homogener Aufbau
Homogenes Erscheinungsbild
Gute Integration in das Projektmanagement
Leicht zu aktualisieren
Das Programm javadoc gehört seit Version 1.0 zum JDK
Folie 209 : Javadoc
Die automatische Erzeugung der Dokumentation stützt sich auf im Quelltext stehende
Dokumentationskommentare
Diese verwenden eine spezielle Syntax
Die Syntax erlaubt die Strukturierung von Kommentaren und Querverweise zu anderen
Programmteilen oder anderen Dokumenten
Eingabe für javadoc sind Java-Quellcode Dateien mit Dokumentationskommentaren
Ausgabe von javadoc sind Dateien mit HTML-Dokumenten
Folie 210 : Javadoc
Die generierte Dokumentation enthält folgende Elemente
Grafisch dargestellte Klassenhierarchien
Übersichten über die zu einem Paket gehörenden Klassen, Interfaces und Ausnahmen
Eine alphabetisch sortierte Liste aller Variablen einer Klasse zusammen mit Angaben zu
Typen und Modifieren
Eine Liste aller Konstruktoren
Eine alphabetisch sortierte Liste aller Methoden einer Klasse zusammen mit Angaben
zu Parametern, Rückgabetyp und Ausnahmen
Folie 211 : Dokumentationskommentare
Syntax der Dokumentationskommentare
/**
* Dies ist ein Dokumentationskommentar
* ...
*/
Unterschied: der Kommentar beginnt mit /** anstelle von /*
Zwischen /** und */ muss jede Zeile mit * gefolgt von einem Leerzeichen beginnen
Ein Dokumentationskommentar teilt sich in zwei Teile auf:
Allgemeiner Kommentar
Tag-Abschnitt
Folie 212 : Dokumentationskommentare
Der Tag-Abschnitt beginnt in der ersten Zeile, welche das Zeichen @ enthält
Javadoc stellt zahlreiche Tags zur Verfügung, sie werden von Javadoc verarbeitet
Ein Tag hat die Form @Name
Beispiel:
/**
* Diese Klasse implementiert eine Warteschlange
* @see java.util.Stack
*/
Leerzeichen und * nicht weglassen: * @see
Folie 213 : Dokumentationskommentare
Ein allgemeiner Kommentar kann einfacher ASCII-Text sein oder mit HTML ausgezeichnet
sein
D.h. kommt das Zeichen < außerhalb eines HTML-Tags vor, so muss in der Form <
geschrieben werden
Beispiel:
/**
* Die Klasse <code>Zahl</code> stellt Zahlen dar.
* Wertebereich: 0 < x < 20000
*/
Folie 214 : Dokumentationskommentare
Dokumentationskommentare müssen jeweils genau vor der zu dokumentierenden Einheit
stehen
Folgenden Einheiten können dokumentiert werden:
Klassen
Interfaces
Methoden
Variablen
Dokumentationskommentare an anderen Stellen werden ignoriert
Folie 215 : Dokumentation von Klassen und Interfaces (Beispiel)
package blatt7;
import java.io.*;
/**
* Das Interface StringStack vereinbart eine
* Schnittstelle für einen Stack in dem nur Instanzen der
* Klasse String abgelegt werden können. Das
* Interface vereinbart neben den normalen Stackoperation zusätzlich
* noch Methoden zur Bestimmung der Länge des obersten Strings und
* aller Strings im Stack.
*
* @author Frank N. Stein
* @version 1.2
* @since
1.0
* @see
blatt7.StringStackDel
* @see
blatt7.StringStackVer
* @see
java.util.Stack
*/
public interface StringStack extends Serializable {
Folie 216 : Dokumentation von Klassen und Interfaces
Für die Dokumentation von Klassen und Interfaces sind folgende Tags zulässig
Tag
Bedeutung
Eintrag
@see
Erzeugt einen Querverweis
See also:
@since
Angabe einer Version des Paketes in der
diese Klasse eingeführt wurde
Since:
@deprecated
Zeigt an, dass diese Klasse nicht mehr
benutzt werden sollte
Deprecated
@author
Angaben über den oder die Autoren der
Klasse
Author:
@version
Versionsnummer der Klasse
Version:
Folie 217 : Dokumentation von Methoden (Beispiel)
/**
* Diese Methode serialisiert den Stack und speichert ihn
* in einer Datei.
* Der Aufruf der Methode ändert nicht den StringStack.
*
* @param name den Namen der Datei in die der serialisierte
* Stack geschrieben wird.
* @exception IOException
*
falls beim Schreiben ein Fehler auftritt.
*/
public void speichern(String name) throws IOException;
Folie 218 : Dokumentation von Konstruktoren (Beispiel)
/**
* Erzeugt einen neuen StringStack mit den Strings
* des angebenen Feldes. Die Strings werden in der Reihenfolge
* eingefügt, in der sie in den Feld sind.
*
* @param a ein Feld mit Strings
* @exception StringStackException
*
falls <code>null</code> in dem Feld auftauchen.
*/
public StringStackDel (String[] a) throws StringStackException {
Folie 219 : Dokumentation von Methoden und Konstruktoren
Für die Dokumentation von Methoden sind folgende Tags zulässig
Tag
Bedeutung
Eintrag
@see
Erzeugt einen Querverweis
@since
Angabe einer Version des Paketes in der
Since:
diese Klasse eingeführt wurde
@deprecated
Zeigt an, dass diese Klasse nicht mehr
benutzt werden sollte
Deprecated
@param
Angaben zu einem Parameter
Parameters:
@returns
Angaben zum Rückgabewert
Returns:
@throws
Angabe zu geworfenen Ausnahmen
Throws:
@exception
Gleiche Bedeutung wie @throws
Throws:
See also:
Folie 220 : Verwendungsformen für @see package.class#member
Referenzen auf die eigene Klasse
@see #variable
@see #methode(Typ, Typ,...)
@see #methode(Typ argname, Typ argname,...)
Referenzen auf andere Klassen im aktuellen oder in importierten Paketen
@see Klasse#variable
@see Klasse#methode(Typ, Typ,...)
@see Klasse#methode(Typ argname, Typ argname,...)
@see Klasse
Referenzen auf ein anderes Paket (voll qualifizierte Namen)
@see package.Klasse#variable
@see package.Klasse#methode(Typ, Typ,...)
@see package.Klasse#methode(Typ argname, Typ argname,...)
@see package.Klasse
@see package
Folie 221 : Beispiele für @see package.class#member
Typ
Beispiel
@see
Darstellung
@see String#toLowerCase()
toLowerCase()
(Klassenname wird weggelassen)
@see Character#toLowerCase(char)
Character.toLowerCase(char)
(Klassenname wird angegeben)
Referenz in
die eigene
Klasse
@see
Referenz auf
eine andere
Klasse
Folie 222 : Dokumentation von Variablen
Für die Dokumentation von Variablen sind folgende Tags zulässig
Tag
Bedeutung
Eintrag
@see
Erzeugt einen Querverweis
@since
Angabe einer Version des Paketes in der
Since:
diese Klasse eingeführt wurde
@deprecated
Zeigt an, dass diese Klasse nicht mehr
benutzt werden sollte
Folie 223 : Aufrufparameter von Javadoc
Das Programm javadoc akzeptiert zahlreiche Aufrufparameter
Allgemeine Syntax von javadoc:
See also:
Deprecated
javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]
options: Programmoptionen
packagenames: Eine Folge der
Namen der Pakete (durch Leerzeichen getrennt), welche
dokumentiert werden sollen
sourcefiles: Eine Folge von Namen von einzelnen Java-Klassen (durch Leerzeichen
getrennt), welche dokumentiert werden sollen
@files: Eine Datei mit Namen von Paketen und Java-Klassen, welche dokumentiert werden
sollen (ein Name pro Zeile)
Folie 224 : Aufrufparameter von Javadoc (Beispiel)
Aufruf von javadoc zur Dokumentation des Paketes blatt7
javadoc -locale de_DE
-d apidocs
-overview blatt7/overview.html
-windowtitle "StringStack API"
-doctitle "StringStack API"
-header "<b>StringStack API</b><br>V 1.0"
-footer "FH Wiesbaden 2001"
-bottom "© 1999-2001 - Frank N. Stein"
-author
-version
-use blatt7
Hinweis: Batch-Datei bzw. Shell-Skript verwenden
Folie 225 : Optionen von Javadoc
-public: Nur öffentliche Methoden und Variablen
-protected: Nur public und protected Methoden und Variablen
-private: Alle Methoden und Variablen
-d directory: Zielverzeichnis für die Dokumentation
-use: Generiert Übersicht über die Verwendung der Klasse
-version: @version Tag beachten
-author: @autor Tag beachten
-windowtitle title: Text für HTML-Tag title
-overview file: Name einer Datei mit einem Übersichtstext
Folie 226 : Optionen von Javadoc
-header header: HTML-Code, welcher am Anfang jedes HTML-Dokumentes erscheint
-footer footer: HTML-Code, welcher am Ende jedes HTML-Dokumentes erscheint
-nonavbar: Es wird keine Navigationsleiste erstellt
-noindex: Es wird kein Index generiert
-notree: Es wird keine Hierarchieansicht generiert
-stylesheetfile: CSS-Stylesheet
-use : Generiert Übersicht über die Verwendung der Klasse
-charset name: Zeichenkodierung (z.B. iso-8859-1)
Folie 227 : Doclets
Doclets sind Java-Klassen zur Erweiterung oder Veränderung der Funktionalität von javadoc
Sie benutzen die Doclet API
Doclets können z.B. verwendet werden, um die Dokumentation in einem Format zu
generieren, welches externe Anwendungen wie beispielsweise CASE-Tools, verarbeiten
können
Mit Doclets kann auch eine graphische Darstellung der Klassen (etwa im UML-Stil) generiert
werden (z.b. beim Reengineering)
Die Doclet-Klassen befinden sich in dem Paket com.sun.doclet
Kapitel 10: JAR: Java-Archive
Folie 228 : Java-Archive
JAR-Dateien sind Archive im ZIP-File Format
Zur Erstellung von Java-Archiven steht das Werkzeug jar zur Verfügung (seit Version 1.1
Bestandteil des JDK)
Die Parameter bei der Verwendung sind ähnlich zur den des UNIX Programmes tar
Ein mit jar erstelltes Archiv kann mit dem Programm zip oder winzip untersucht bzw.
entpackt werden
Vorteil: jar kann plattformübergreifend eingesetzt werden
Folie 229 : Verwendung von jar
Aufruf des Programmes jar:
jar [ options ] [manifest] destination input-file [input-files]
destination:
Angabe des Names des JAR-Archives (üblicherweise wird die Endung jar
verwendet)
input-files:
Liste der zu archivierenden Dateien oder Verzeichnisse (durch Leerzeichen
getrennt)
Beispiel:
jar cf blatt7.jar blatt7/*.class blatt6
Folie 230 : Erzeugung eines JAR-Archives
Aufruf:
jar cf jar-file input-file(s)
Optionen:
c: Erzeugung eines Archives
f: Name des JAR-Archives (muss die letzte Option sein)
v: Ausgabe der Aktionen
0: Keine Kompression
m: Angabe einer Manifestdatei
Folie 231 : Erzeugung eines JAR-Archives (Beispiel)
Beispiel:
jar cvmf MANIFEST.MF stack.jar blatt7\*.class
Ausgabe:
Manifest wurde hinzugefügt.
Hinzufügen von: blatt7/Clock.class(ein = 1197) (aus= 725)(komprimiert 39 %)
Hinzufügen von: blatt7/StringStack.class(ein = 643) (aus= 348)(komprimiert 45 %)
Hinzufügen von: blatt7/StringStackDel.class(ein = 3259) (aus= 1751)(komprimiert 46 %)
Hinzufügen von: blatt7/StringStackEventHandler.class(ein = 3135) (aus= 1715)(komprimiert 45
Hinzufügen von: blatt7/StringStackException.class(ein = 288) (aus= 226)(komprimiert 21 %)
Hinzufügen von: blatt7/StringStackFrame$1.class(ein = 590) (aus= 377)(komprimiert 36 %)
Hinzufügen von: blatt7/StringStackFrame.class(ein = 4462) (aus= 2314)(komprimiert 48 %)
Hinzufügen von: blatt7/StringStackTester.class(ein = 4904) (aus= 2478)(komprimiert 49 %)
Hinzufügen von: blatt7/StringStackVer.class(ein = 2694) (aus= 1434)(komprimiert 46 %)
Folie 232 : Umgang mit JAR-Archiven
Auflisten des Inhaltes:
jar tf stack.jar (oder auch unzip -l stack.jar)
Entpacken:
jar xf stack.jar (oder auch unzip stack.jar)
Beispiel:
jar tvf stack.jar
0
197
1197
643
3259
3135
288
590
4462
4904
2694
Wed
Wed
Wed
Wed
Wed
Wed
Wed
Wed
Wed
Wed
Wed
Dec
Dec
Dec
Dec
Dec
Dec
Dec
Dec
Dec
Dec
Dec
12
12
12
12
12
12
12
12
12
12
12
10:22:16
10:22:16
10:16:18
10:16:18
10:16:18
10:16:18
10:16:18
10:16:18
10:16:18
10:16:18
10:16:18
CET
CET
CET
CET
CET
CET
CET
CET
CET
CET
CET
2001
2001
2001
2001
2001
2001
2001
2001
2001
2001
2001
META-INF/
META-INF/MANIFEST.MF
blatt7/Clock.class
blatt7/StringStack.class
blatt7/StringStackDel.class
blatt7/StringStackEventHandler.class
blatt7/StringStackException.class
blatt7/StringStackFrame$1.class
blatt7/StringStackFrame.class
blatt7/StringStackTester.class
blatt7/StringStackVer.class
Folie 233 : Umgang mit JAR-Archiven
Hinzufügen von Dateien:
jar uf stack.jar images\*.gif
Alle Dateien mit der Endung gif aus dem Verzeichnis images werden zusätzlich in das Archiv
stack.jar eingefügt
Eventuell schon existierende Dateien werden überschrieben
Die Option -C kann in Zusammenhang mit den Optionen x und u verwendet werden. Sie
veranlasst jar in das nach der Option angegebene Verzeichnis zu wechseln
Beachten Sie den Unterschied:
jar uf stack.jar images\*.gif
jar uf stack.jar -C images *.gif
Folie 234 : Verwendung von JAR-Archiven
JAR-Archive dienen in erster Linie der Verteilung von Java-Anwendung in einer einzigen
Datei
Um Java-Klassen aus JAR-Archiven anderen Anwendungen zugänglich zu machen, müssen
JAR-Archive nicht entpackt werden
Es genügt, ein JAR-Archiv in den CLASSPATH aufzunehmen
Java-Klassenlader entnehmen benötigte Dateien automatisch aus JAR-Archiven
Beispiel:
CLASSPATH=$HOME/java/classes:$HOME/jars/stack.jar:$HOME/jars/db.jar
Folie 235 : Verwendung von JAR-Archiven in Applets
Bei Applets haben JAR-Archive den Vorteil, dass die Anzahl der Netzwerkverbindungen
gesenkt werden kann
Anstatt für jede einzelne Klasse oder für jedes Bild eine Verbindung aufzubauen, kann das
gesamte Archiv auf einmal übertragen werden
<applet code=Calendar.class
archive="Calendar.jar"
width=120 height=120>
</applet>
Folie 236 : Manifestdateien
JAR-Archive können Meta-Informationen in Form einer Manifestdatei enthalten
Manifestdateien werden in einem speziellen Verzeichnis abgelegt: META-INF
Manifestdateien sind einfach strukturierte Textdateien, pro Zeile enthalten Sie ein Paar der
Form
Name: Wert
Die Manifest-Spezifikation legt die zulässigen Namen und ihre Bedeutung fest
Manifestdateien können bei der Erzeugung eines JAR-Archives mit der Option m angegeben
werden
Folie 237 : Manifestdateien
Manifestdatei MANIFEST.MF für die StringStack-Klassen
Manifest-Version: 1.0
Created-By: 1.3.1 (Sun Microsystems Inc.)
Main-Class: blatt7.StringStackFrame
Name: "StringStackFrame"
Implementation-Vendor: V. Turau
Implementation-Version: 1.0
Am Ende muss eine Leerzeile stehen!!!
Erzeugen des Archives mit
jar -cvmf MANIFEST.MF stack.jar blatt7\*.class
Die in einer Manifestdatei kann durch Werkzeuge genutzt werden
Folie 238 : Verwendung von Manifestdateien
Der Eintrag Main-Class verweist auf eine Klasse mit einer main-Methode
Der Aufruf
java -jar stack.jar
bewirkt, dass die main-Methode der unter Main-Class angegebenen Klasse ausgeführt wird
Unter manchen Betriebssystemen (u.a. Win32, Solaris) bewirkt ein Doppel-Click auf ein
JAR-Archiv, den Start der Anwendung
Vorteil: Wesentlich einfachere Verteilung und Anwendung von Java-Programmen
Folie 239 : Manifestdateien
Manifestdateien haben noch zahlreiche andere Verwendungen:
Versionierung
Abhängikeiten zwischen JAR-Archiven
Digitale Signaturen
Indizierung
Das Paket java.util.jar enthält Klassen für den Umgang mit JAR-Archiven