Dokumentieren mit Javadoc 2
Javadoc
Was ist Javadoc?
Javadoc ist ein Werkzeug, dass eine standardisierte Dokumentation für die Programmiersprache Java unterstützt.
Vorteil:• Dokumentation findet während der Programmierung statt• Code und Dokumentation kann im Quelltext stehen
Woher bekomme ich Javadoc?
Javadoc ist in jedem Java 2 SDK von Sun Microsystems enthalten. Nach der Installation befindet es sich im gleichen Verzeichnis wie Javac.
Dokumentieren mit Javadoc 3
Javadoc
Wie funktioniert Javadoc?
Javadoc benutzt Javac um an Deklarationen und Doc Comments der Quellcoddateien zu gelangen. Es können auch weitere Dateien eingebunden werden.Aus diesen Informationen wird eine HTML basierte Dokumentation erzeugt.
Was sind Doc Comments?
Doc Comments werden Kommentare mit folgender Syntax genannt:
/*** Dieser Kommentar wird als Doc Comment interpretiert.*/
Dokumentieren mit Javadoc 4
Javadoc
Welche Dateien werden von Javadoc berücksichtigt?
Javadoc erstellt die Dokumentation aus folgenden Dateien:
• Quellcodedateien• Package Bemerkungen• Overview Bemerkungen • diverse weiteren Dateien
Dokumentieren mit Javadoc 5
Javadoc
Quellcodedateien
Doc Comments in Quellcodedateien können vor
• Klassen• Konstuktoren• Datentypen• Methoden stehen.
Doc Comments werden aber nur beachtet wenn sie genau vor einer Deklarationstehen!
Dokumentieren mit Javadoc 6
Javadoc
Der erste Satz enthält eine Kurzbeschreibung, der Rest eine ausführliche Beschreibung.Doc Comments werden als HTML ausgelesen, weshalb HTML Syntax enthalten sein kann.
Vermieden werden sollte:
• Überschriftformatierung in HTML
<H1> … </H1>..<H6> … <H6>
Dokumentieren mit Javadoc 7
Javadoc
• Zusammenfassung von Beschreibungen
Beispiel:/** *The horizontal and vertical distances of point (x,y) */public int x, y;
Ausgabe von Javadoc:
public int xThe horizontal and vertical distances of point (x,y)
public int yThe horizontal and vertical distances of point (x,y)
Dokumentieren mit Javadoc 8
Javadoc
Package Bemerkungen
Für jedes Package kann eine Beschreibung geschrieben werden.
Es muss eine Datei erstellt werden die den Namen package.html trägt.Diese Datei muss in das Verzeichnis des Packages abgelegt werden.
Die Datei package.html benötigt kein Doc Comments, sie enthält nur HTML. Entscheidend ist was zwischen <body> …</body> steht. Javadoc bindet diese Datei automatisch ein. Der erste Satz ist wieder eine Kurzbeschreibung, danach folgt eine ausführliche Beschreibung.
Dokumentieren mit Javadoc 9
Javadoc
Overview Bemerkungen
In diese HTML Datei kommen Beschreibungen die für die ganze Anwendung gelten.
Sie ist wie die Datei package.html ohne Doc Comments. Entscheidend ist auch hier was zwischen <body> …</body> steht. Der erste Satz ist wieder die Kurzbeschreibung danach kommt eine ausführlicheBeschreibung.
Diese Datei braucht keinen speziellen Namen. Wenn Javadoc ausgeführt wirdmuss dieser Dateiname angegeben werden.
Dokumentieren mit Javadoc 10
Javadoc
Einbindung weiterer Dateien
Diese Dateien werden von Javadoc in das Ausgabeverzeichnis der Dokumentation kopiert. Dies können weitere HTML Dateien sein, Applets, Beispielcode aber auch Grafiken die in die Dokumentation eingebunden werden.Diese Dateien müssen in einem Verzeichnis unterhalb des Packages abgelegt sein, welches ../doc-files/ heißen muss.Zugriff kann innerhalb der Doc Comments so erfolgen:
/**
* This button looks like this: * <img src="doc-files/Button.gif"> */
Dokumentieren mit Javadoc 11
Javadoc
Javadoc Tags
Es gibt spezielle Schlüsselwörter welche als Tags bezeichnet werden. Tags werden mit einem beginnenden @ gekennzeichnet.
Übersicht über mögliche Tags:
author deprecated docRootexception inheritDoc linklinkplain param returnsee serial serialDataserialField since throwsvalue version
Dokumentieren mit Javadoc 12
Javadoc
Es gibt Block Tags and In-line Tags.
Block Tags müssen am Anfang eines Doc Comments stehen, ansonsten wird ein Tagnicht erkannt.
In-line Tags können überall stehen, müssen allerdings mit geschweiften Klammern umgeben sein.
/*** @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)} */
Dokumentieren mit Javadoc 13
Javadoc
Wo können welche Javadoc Tags benutzt werden?
X@exception
X@throws
XXX@serial
XXX@deprecated
XXX@version
XXX@author
XXXXX@since
XXXXX@see
OverviewPackageKonstruktor,Methoden
DatentypenKlasse, Interface
Dokumentieren mit Javadoc 14
Javadoc
X@inheritDoc
X@value
XXXXX@docRoot
XXXXX@linkplain
XXXXX@link
X@serialField
X@serialData
X@return
X@param
OverviewPackageKonstruktor,Methoden
DatentypenKlasse, Interface
Dokumentieren mit Javadoc 15
Javadoc
Beispiel:
package motorbetrieben;import java.io.*;/*** Diese Klasse legt ein Auto an.* <br>Eine Datei mit dem Namen des Autos wird angelegt. * Autoname und Anzahl der Gänge wird in dieser Datei gespeichert. * <br>Hier sehen Sie eine Darstellung eines Autos: * <br><img src="doc-files/auto.jpg">* * @author Johannes Rinn* @version 1.0 */
public class Auto {
/** Legt eine neue Datei an. */protected File AutoDatei = null; /** Durch diesen Filewriter kann in eine Datei geschrieben werden.* Der Filewriter kann auch aus einer Datei lesen. */
protected FileWriter AutoDateiSchreiber = null;
Listing 1/3
Dokumentieren mit Javadoc 16
Javadoc
/*** Ein neues Auto wird angelegt. * <br>Der Konstruktor ruft die Funktion sichereAuto() auf, und * das Auto wird gespeichert* * @param Name Der Name des Autos.* @param AnzahlGaenge Die Anzahl der Gänge des Fahrzeuges. */
public Auto (String Name,int AnzahlGaenge){
if (sichereAuto(Name, AnzahlGaenge)){System.out.println("Auto gesichert!");}else{System.out.println("Auto nicht gesichert!");}
}
Listing 2/3
Dokumentieren mit Javadoc 17
Javadoc
/*** Sichert Auto in eine Datei. * <br> Eine Datei mit dem Namen des Autos wird angelegt.* <br> Der Autoname und die Anzahl der Gänge wird gespeichert.* * @param Gaenge gibt die Anzahl der Gänge des Autos an.* @param Autoname gibt den Namen des Autos an.* @throws IOExeption wird geworfen wenn nicht in die Datei geschreiben werden kann.* @return true - wenn das Auto in einer Datei abgespeichert werden konnte.*/
public boolean sichereAuto(String Autoname, int Gaenge){
AutoDatei = new File(Autoname);boolean gespeichert = false;try{
AutoDateiSchreiber = new FileWriter(AutoDatei+".txt",false);AutoDateiSchreiber.write(Autoname +" Anzahl Gänge "+ Gaenge);AutoDateiSchreiber.close();gespeichert = true;
}
catch (IOException e) {
e.printStackTrace();}
return gespeichert;}
}
Listing 3/3
Dokumentieren mit Javadoc 18
Javadoc
Im Projekt Fahrzeuge gibt es drei Packages
• fahrzeuge• motorbetrieben• nichtmotorbetrieben
Jedes Package besitzt eine package.html die imentsprechenden Package Verzeichnis liegt.
Die Packages motorbetrieben und nichtmotorbetrieben habenein Verzeichnis doc-files in welchem zusätzliche Dateienliegen, auf die in einem Doc Comment verwiesen wird.Die Datei overview.html liegt willkürlich im Package motorbetrieben.
Ordnerstruktur:
Dokumentieren mit Javadoc 19
Javadoc
Der Aufruf von Javadoc kann über die Konsole aber auch über Compiler wieEclipse erfolgen.
Dokumentieren mit Javadoc 20
Javadoc
Im nächsten Fenster kann der Pfad zuJavadoc, und das Doclet, welches die Art der Ausgabe bestimmt, angegeben werden.
Außerdem kann ausgewählt werden, ob Inhalte die private deklariert wurden in derDokumentation angezeigt werden.
Dokumentieren mit Javadoc 26
Javadoc
Sind andere Formate außer HTML möglich?
Javadoc benutzt Doclets um Dokumentationen zu erstellen.Mit dem Standard Doclet wird HTML erzeugt, es können aber andere Docletseingebunden werden.
Beispiele:• Windows Help Format• PDF• XML
Dokumentieren mit Javadoc 27
Javadoc
Ähnliche Werkzeuge die zur Dokumentation benutzt werden können:
• Doxygen
http://www.doxygen.orgerstellt Dokumentationen für C++, C, IDL, Java und C#
• Doc++ http://docpp.sourceforge.neterstellt Dokumentationen für C, C++, IDL und Java