Einführung in Javadoc - hs-weingarten.dekeller/Downloads/grabo/java/... · Dokumentieren mit Javadoc 2 Javadoc Was ist Javadoc? Javadoc ist ein Werkzeug, dass eine standardisierte

Einführung in Javadoc

Johannes Rinn

http://java.sun.com/j2se/javadoc

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.


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.*/


Javadoc

Welche Dateien werden von Javadoc berücksichtigt?

Javadoc erstellt die Dokumentation aus folgenden Dateien:

• Quellcodedateien• Package Bemerkungen• Overview Bemerkungen • diverse weiteren Dateien


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!


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>


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)


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.


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.


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"> */


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


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)} */


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


Javadoc

X@inheritDoc

X@value

XXXXX@docRoot

XXXXX@linkplain

XXXXX@link

X@serialField

X@serialData

X@return

X@param

OverviewPackageKonstruktor,Methoden

DatentypenKlasse, Interface


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


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


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


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:


Javadoc

Der Aufruf von Javadoc kann über die Konsole aber auch über Compiler wieEclipse erfolgen.


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.


Javadoc


Javadoc

Ausgabe:


Javadoc


Javadoc


Javadoc


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


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


Javadoc

Weitere Informationen finden Sie bei:

How to Write Doc Comments for the Javadoc Tool

http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

Documents

Einführung in Javadoc - hs-weingarten.dekeller/Downloads/grabo/java/... · Dokumentieren mit Javadoc 2 Javadoc Was ist Javadoc? Javadoc ist ein Werkzeug, dass eine standardisierte