Der Dokumentationsgenerator Javadoc

• Aufruf von javadoc  (ab Version 1.2)

 

 
 
 
 
 

allgemein:

javadoc  [options]    [packagenames]   [sourcefiles]    [@files]
 

Parameter (in beliebiger Reihenfolge):
 

options	javadoc-spezifische Kommando-Optionen. Eine komplette Übersicht ist mit javadoc -help erhältlich. Einige nützliche Optionen werden nachstehend erläutert.
packagenames	Liste von Paketnamen, getrennt durch Leerzeichen. Wildcard-Bezeichnungen mit  * sind nicht erlaubt. Ist die CLASSPATH-Variable gesetzt, werden die Pakete entsprechend gesucht. Liegen die Pakete in einem anderen Verzeichnis, kann man den Pfad mittels der -sourcepath Option angeben.
sourcefiles	Liste der Namen von Java-Quelldateien (.java), getrennt durch Leerzeichen. Vorangestellte Pfadangaben legen fest, in welchem Verzeichnis die Quelldateien von javadoc gesucht werden. Wildcard-Bezeichnungen mit  * sind erlaubt.
@files	Eine oder mehrere Dateien, die Paketnamen und Namen (keine Wildcards!) von Quelldateien in beliebiger Reihenfolge enthalten.


 

Einfachster Aufruf mit Standard-Einstellungen lautet:

javadoc abc.java

Es wird im aktuellen Verzeichnis die Java-Quelle abc.java ausgewertet. Man findet anschließend im selben Verzeichnis die Datei abc.html,  die man sich mit einem geeigneten Browser (Netscape) ansehen kann. Außerdem werden von javadoc diverse andere HTML-Dateien erzeugt, die in der Dokumentationshierarchie benötigt werden. Man kann daher auch direkt index.html öffnen, von dort gelangt man zu allen weiteren Klassen- und Methodendokumentationen.

Achtung !!!
Hat man in demselben Verzeichnis z.B. außerdem die Datei xyz.java und ruft dann mit dem Befehl  javadoc xyz.java erneut den Dokumentationsgenerator auf, so werden die erzeugten HTML-Dateien überschrieben!!!  Getrennte Dokumentationen sollten daher in getrennten Unterverzeichnissen erzeugt werden. Falls man jedoch für abc.java und xyz.java eine gemeinsame Dokumentation erstellen will, lautet der Befehl javadoc abc.java xyz.java (ebenso möglich: javadoc *.java). Mittels der Datei index.html kann man sich über beide Java-Quellen gemeinsam informieren.
 
 
 
 

• Einige nützliche Optionen für javadoc

 

-help	gibt alle Optionen auf dem Bildschirm aus
-verbose	ausführliche Informationen während der Laufzeit von javadoc
-d directory	Pfadname, in welchem die erzeugten HTML-Ausgabedateien abgelegt werden sollen
-sourcepath Pfadname	Pfadname, in welchem die Pakete gesucht werden
-author	@author Paragraph berücksichtigen
-version	@version Paragraph berücksichtigen
-header html-code	HTML-Zeichenkette (in " "eingeschlossen) als Text für Kopfzeile auf jeder Dokumentationsseite
-footer html-code	HTML-Zeichenkette als Text für Fußzeile auf jeder Dokumentationsseite


 
 
• Aufbereitung der Java-Quelldatei

 
1. Unberücksichtigt bleiben Kommentare, die von /* ... */ eingeschlossen sind oder von // eingeleitet werden, z.B.:

/* Dieser Kommentar wird von javadoc nicht ausgewertet ! */
// Dies gilt ebenso für diesen Kommentar.
 
2. Javadoc wertet Kommentare aus, die von /** ... */ eingeschlossen sind. Diese javadoc-Kommentare stehen unmittelbar vor den Deklarationsteilen von Klasse, Interface, Methode, Konstruktor oder Feld.  Vor jeder Deklaration darf höchstens ein (!) Kommentar stehen.

Beispiel:
/** Dieser Kommentar beinhaltet eine Beschreibung der Klasse ddformeln */
public class ddformeln
     ..... weitere Java-Quellzeilen ...
/** Dieser Kommentar beschreibt die Methode fakr */
public long fakr(int n)
     ..... weitere Java-Quellzeilen ...
 
3. Die javadoc-Kommentare können sich über mehrere Quellzeilen erstrecken. Folgezeilen werden am Anfang mit * gekennzeichnet.

Beispiel:
/**  Dieser Kommentar beinhaltet die erste Zeile,
*     dann folgt die 2. Zeile,
*     dann die 3. des Kommentars zur Klasse ddformeln */
public class ddformeln
 
4. Die javadoc-Kommentare werden als HTML-Zeilen interpretiert. Man kann also HTML-Tags verwenden.

Beispiel:
/**  Dieser Kommentar beinhaltet die erste Zeile,
*     <br> javadoc erstellt nun einen Zeilenumbruch für den Rest des Kommentars. */
 
5. javadoc-Tags

Innerhalb der javadoc-Kommentare können bestimmte Tags gesetzt werden, die zur Dokumentationsaufbereitung verwendet werden. Für einfachere Dokumentationen sind folgende Tags sinnvoll:

@author Autorenname                                       (nur im Kommentar zur Klasse)

@version Versionsnummer                               (nur im Kommentar zur Klasse)

@param Parametername Beschreibung des Parameters

@return Beschreibung des Return-Parameters