From 33613a85afc4b1481367fbe92a17ee59c240250b Mon Sep 17 00:00:00 2001 From: Sven Eisenhauer Date: Fri, 10 Nov 2023 15:11:48 +0100 Subject: add new repo --- .../hjp5/html/k100322.html | 426 +++++++++++++++++++++ 1 file changed, 426 insertions(+) create mode 100644 Master/Reference Architectures and Patterns/hjp5/html/k100322.html (limited to 'Master/Reference Architectures and Patterns/hjp5/html/k100322.html') diff --git a/Master/Reference Architectures and Patterns/hjp5/html/k100322.html b/Master/Reference Architectures and Patterns/hjp5/html/k100322.html new file mode 100644 index 0000000..bf458c0 --- /dev/null +++ b/Master/Reference Architectures and Patterns/hjp5/html/k100322.html @@ -0,0 +1,426 @@ + + + +Handbuch der Java-Programmierung, 5. Auflage + + + + + + + + + +
 Titel  + Inhalt  + Suchen  + Index  + DOC  +Handbuch der Java-Programmierung, 5. Auflage +
 <<  +  <   +  >   + >>  + API  +Kapitel 51 - Hilfsprogramme des JDK +
+
+ + + + +

51.5 javadoc - Der Dokumentationsgenerator +

+
+ +
+ + + + +

51.5.1 Aufruf

+

+ + + + +
+ +
+javadoc [ options ] { package | sourcefile }
+
+ +
+ + + + +

51.5.2 Beschreibung

+ +

+javadoc +ist ein Programm, das aus Java-Quelltexten Dokumentationen im HTML-Format +erstellt. Dazu verwendet es die öffentlichen Klassen-, Interface- +und Methodendeklarationen und fügt zusätzliche Informationen +aus eventuell vorhandenen Dokumentationskommentaren hinzu. Zu jeder +Klassendatei xyz.java wird eine HTML-Seite +xyz.html generiert, die über verschiedene +Querverweise mit den anderen Seiten desselben Projekts in Verbindung +steht. Zusätzlich generiert javadoc +diverse Index- und Hilfsdateien, die das Navigieren in den Dokumentationsdateien +erleichtern. + + + + +

51.5.3 Dokumentationskommentare

+ +

+Bereits ohne zusätzliche Informationen erstellt javadoc +aus dem Quelltext eine brauchbare Beschreibung aller Klassen und Interfaces. +Durch das Einfügen von Dokumentationskommentaren kann die Ausgabe +zusätzlich bereichert werden. Ein Dokumentationskommentar beginnt +mit /** +und endet mit */ und ähnelt +damit einem gewöhnlichen Kommentar. Er muss im Quelltext immer +unmittelbar vor dem zu dokumentierenden Item platziert werden (einer +Klassendefinition, einer Methode oder einer Instanzvariable). Er kann +aus mehreren Zeilen bestehen. Die erste Zeile des Kommentars wird +später als Kurzbeschreibung verwendet. +

+ + + + + + + + + +
+ +

+Zur Erhöhung der Übersichtlichkeit darf am Anfang jeder +Zeile ein Sternchen stehen, es wird später ignoriert. Innerhalb +der Dokumentationskommentare dürfen neben normalem Text auch +HTML-Tags vorkommen. Sie werden unverändert in die Dokumentation +übernommen und erlauben es damit, bereits im Quelltext die Formatierung +der späteren Dokumentation vorzugeben. Die Tags <h1> +und <h2> sollten möglichst +nicht verwendet werden, da sie von javadoc +selbst zur Strukturierung der Ausgabe verwendet werden.

 + + + + +
 Hinweis 
+
+ +

+javadoc +erkennt des weiteren markierte Absätze innerhalb von Dokumentationskommentaren. +Die Markierung muss mit dem Zeichen @ +beginnen und - abgesehen von Leerzeichen - am Anfang der Zeile stehen. +Jede Markierung leitet einen eigenen Abschnitt innerhalb der Beschreibung +ein, alle Markierungen eines Typs müssen hintereinanderstehen. +Tabelle 51.5 gibt eine Übersicht +der wichtigsten Markierungen und beschreibt, wie sie verwendet werden. + +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Markierung und ParameterDokumentationVerwendung in
@author nameErzeugt einen Autoreneintrag.Klasse, Interface
@version versionErzeugt einen Versionseintrag. Darf höchstens +einmal je Klasse oder Interface verwendet werden.Klasse, Interface
@since jdk-versionBeschreibt, seit wann das beschriebene Feature +existiert.Klasse, Interface
@see referenceErzeugt einen Querverweis auf eine andere +Klasse, Methode oder einen beliebigen anderen Teil der Dokumentation. +Gültige Verweise sind: +
    +
  • @see java.util.Vector +
  • @see Vector +
  • @see Vector#addElement +
  • @see <a href="Spez.html">Spez</a> +
+		Klasse, Interface, Instanzvariable, Methode +
@param name descriptionParameterbeschreibung einer MethodeMethode
@return descriptionBeschreibung des Rückgabewerts einer +MethodeMethode
@exception classname descriptionBeschreibung einer Ausnahme, die von dieser +Methode ausgelöst wirdMethode
@deprecated descriptionMarkiert eine veraltete Methode, die zukünftig +nicht mehr verwendet werden sollte.Methode
+

+Tabelle 51.5: Markierungen in Dokumentationskommentaren

+ + + + +

51.5.4 Aufruf von javadoc

+ +

+Um javadoc +aufzurufen, sollte zunächst in das Verzeichnis gewechselt werden, +in dem sich die zu dokumentierenden Quelldateien befinden. Anschließend +kann durch Eingabe des folgenden Kommandos die Erzeugung der Dokumentationen +für alle Quelldateien gestartet werden: + +

+javadoc *.java
+
+ + +

+Das Programm erzeugt eine Reihe von HMTL-Dateien, die die zu den jeweiligen +Quellen korrespondierenden Dokumentationen enthalten. Zusätzlich +werden eine Reihe von Hilfsdateien zur Darstellung und Indexierung +der Dokumentationsdateien erstellt. + +

+Alternativ zum Aufruf mit einer Reihe von Quelldateien kann javadoc +auch mit Paketnamen als Argument aufgerufen werden. Wenn der Klassenpfad +korrekt gesetzt ist, spielt es dann keine Rolle mehr, aus welchem +Verzeichnis das Programm gestartet wird, denn die Klassendateien werden +automatisch korrekt gefunden. Wenn nicht per Schalter -d +etwas anderes angegeben wurde, erzeugt javadoc +die Dokumentationsdateien im aktuellen Verzeichnis. +

+ + + + + + + + + + + +
+ +

+In den JDKs 1.0 und 1.1 erzeugt javadoc +zwei unterschiedliche Arten von Standardverweisen. Bei der ersten +Art werden Grafiken eingebunden, um Überschriften für die +verschiedenen Dokumentationsabschnitte zu generieren. Damit diese +im Browser korrekt angezeigt werden, muss ein Unterverzeichnis images +angelegt und die erforderlichen Grafikdateien dorthin kopiert werden +(beispielsweise aus \jdk1.1.2\docs\api\images). +Ab dem JDK 1.2 werden dagegen keine Grafikdateien mehr benötigt.

 + + + + +
 JDK1.1-6.0 
+
+ +

+Die zweite Art von Verweisen ist die auf Klassen oder Methoden der +Java-Klassenbibliothek (z.B. java.lang.String). +Im JDK 1.1 geht javadoc +davon aus, dass sich die Dokumentationsdateien zu allen externen Klassen +und Methoden im selben Verzeichnis wie die zu erstellenden Dokumentationsdateien +befinden. Damit also externe Verweise funktionieren, müsste man +die HTML-Files der Originaldokumentation des JDK in sein eigenes Dokumentationsverzeichnis +kopieren, was sicherlich nicht immer praktikabel ist. +

+ + + + + + + + + + + +
+ +

+Mit dem JDK 1.2 wurde die Option -link +eingeführt, mit der ein Pfad auf die Dokumentation der Standardklassen +angegeben werden kann. Der Pfad muss als URL angegeben werden und +das Verzeichnis beschreiben, in dem die Datei package-list +der Dokumentationsdateien liegt. In der Dokumentation zu javadoc +gibt SUN folgendes Beispiel an: + +

+javadoc -link http://java.sun.com/products/jdk/1.2/docs/api ...
+
+ +		 + + + + +
 JDK1.1-6.0 
+
+ +

+Dadurch wird bei Standard-Klassennamen auf die auf dem SUN-Server +liegende Originaldokumentation verwiesen. Soll dagegen auf eine lokal +installierte Dokumentation verwiesen werden, kann auch ein file-URL +angegeben werden. Liegt die Dokumentation des JDK beispielsweise im +Verzeichnis c:\jdk1.6\docs (und somit +die API-Dokumentation im Verzeichnis c:\jdk1.6\docs\api), +kann javadoc +wie folgt aufgerufen werden: + +

+javadoc -link file:///c:/jdk1.6/docs/api ...
+
+ + + + + +

51.5.5 Optionen

+ +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionBedeutung
-classpath pathGibt die Liste der Pfade zur Suche von Klassendateien +an.
-publicNur Elemente des Typs public +werden dokumentiert.
-protectedElemente des Typs public +und protected +werden dokumentiert (das ist die Voreinstellung).
-packageElemente des Typs package, +public +und protected +werden dokumentiert.
-privateAlle Elemente werden dokumentiert.
-versionVersionseintrag generieren
-authorAutoreneintrag generieren
-sourcepath pathPfad mit den Quelldateien
-d directoryVerzeichnis, in dem die generierten Dokumentationsdateien +abgelegt werden. Standardmäßig werden sie im aktuellen +Verzeichnis angelegt.
-verboseAusgabe zusätzlicher Meldungen während +der Dokumentationserstellung
+

+Tabelle 51.6: Einige Optionen von javadoc

+

+ + + + + + + + + + + +
+ +

+Neben den hier erwähnten Schaltern kennt javadoc +(insbesondere seit dem JDK 1.2) eine ganze Reihe zusätzlicher +Optionen, mit denen die Codeerzeugung beeinflusst werden kann. Bemerkenswert +ist dabei auf jeden Fall das Konzept der Doclets, +mit denen das Verhalten von javadoc +und das Aussehen der generierten Dokumentationsdateien weitgehend +verändert werden kann. Doclets sind Zusatzmodule für javadoc, +deren Aufgabe es ist, auf der Basis des Doclet-APIs und der geparsten +Quelltexte die Ausgabedateien zu erzeugen. Ob der generierte Code +dabei im HTML-, RTF- oder einem anderen Format erzeugt wird, spielt +keine Rolle. Das seit dem JDK 1.2 ausgelieferte Standard-Doclet erzeugt +die Dokumentationsdateien im HTML-Format.

 + + + + +
 JDK1.1-6.0 
+
+

+ + + +
 Titel  + Inhalt  + Suchen  + Index  + DOC  +Handbuch der Java-Programmierung, 5. Auflage, Addison +Wesley, Version 5.0.1 +
 <<  +  <   +  >   + >>  + API  +© 1998, 2007 Guido Krüger & Thomas +Stark, http://www.javabuch.de +
+ + + -- cgit v1.2.3