Dokumentieren mit Javadoc
Werbung
Einführung in Javadoc
Johannes Rinn
http://java.sun.com/j2se/javadoc
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
2
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
3
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
4
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 Deklaration
stehen!
Dokumentieren mit Javadoc
5
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
6
Javadoc
• Zusammenfassung von Beschreibungen
Beispiel:
/**
*The horizontal and vertical distances of point (x,y)
*/
public int x, y;
Ausgabe von Javadoc:
public int x
The horizontal and vertical distances of point (x,y)
public int y
The horizontal and vertical distances of point (x,y)
Dokumentieren mit Javadoc
7
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
8
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ührliche
Beschreibung.
Diese Datei braucht keinen speziellen Namen. Wenn Javadoc ausgeführt wird
muss dieser Dateiname angegeben werden.
Dokumentieren mit Javadoc
9
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
10
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
exception
linkplain
see
serialField
value
deprecated
inheritDoc
param
serial
since
version
Dokumentieren mit Javadoc
docRoot
link
return
serialData
throws
11
Javadoc
Es gibt Block Tags and In-line Tags.
Block Tags müssen am Anfang eines Doc Comments stehen, ansonsten wird ein Tag
nicht 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
12
Javadoc
Wo können welche Javadoc Tags benutzt werden?
Klasse,
Interface
Datentypen
Konstruktor,
Methoden
Package
Overview
@see
X
X
X
X
X
@since
X
X
X
X
X
@author
X
X
X
@version
X
X
X
@deprecated
X
X
@serial
X
X
X
X
@throws
X
@exception
X
Dokumentieren mit Javadoc
13
Javadoc
Klasse,
Interface
Datentypen
Konstruktor,
Methoden
@param
X
@return
X
@serialData
X
@serialField
Package
Overview
X
@link
X
X
X
X
X
@linkplain
X
X
X
X
X
@docRoot
X
X
X
X
X
@value
@inheritDoc
X
X
Dokumentieren mit Javadoc
14
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
15
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
16
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
17
Javadoc
Ordnerstruktur:
Im Projekt Fahrzeuge gibt es drei Packages
• fahrzeuge
• motorbetrieben
• nichtmotorbetrieben
Jedes Package besitzt eine package.html die im
entsprechenden Package Verzeichnis liegt.
Die Packages motorbetrieben und nichtmotorbetrieben haben
ein Verzeichnis doc-files in welchem zusätzliche Dateien
liegen, auf die in einem Doc Comment verwiesen wird.
Die Datei overview.html liegt willkürlich im Package
motorbetrieben.
Dokumentieren mit Javadoc
18
Javadoc
Der Aufruf von Javadoc kann über die
Konsole aber auch über Compiler wie
Eclipse erfolgen.
Dokumentieren mit Javadoc
19
Javadoc
Im nächsten Fenster kann der Pfad zu
Javadoc, und das Doclet, welches die Art
der Ausgabe bestimmt, angegeben werden.
Außerdem kann ausgewählt werden, ob
Inhalte die private deklariert wurden in der
Dokumentation angezeigt werden.
Dokumentieren mit Javadoc
20
Javadoc
Dokumentieren mit Javadoc
21
Javadoc
Ausgabe:
Dokumentieren mit Javadoc
22
Javadoc
Dokumentieren mit Javadoc
23
Javadoc
Dokumentieren mit Javadoc
24
Javadoc
Dokumentieren mit Javadoc
25
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 Doclets
eingebunden werden.
Beispiele:
• Windows Help Format
• PDF
• XML
Dokumentieren mit Javadoc
26
Javadoc
Ähnliche Werkzeuge die zur Dokumentation benutzt
werden können:
• Doxygen
http://www.doxygen.org
erstellt Dokumentationen für C++, C, IDL, Java und C#
• Doc++
http://docpp.sourceforge.net
erstellt Dokumentationen für C, C++, IDL und Java
Dokumentieren mit Javadoc
27
Javadoc
Weitere Informationen finden Sie bei:
How to Write Doc Comments for the Javadoc Tool
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
Dokumentieren mit Javadoc
28
