Einführung in Javadoc

Größe: px

Ab Seite anzeigen:

Download "Einführung in Javadoc"

Anton Auttenberg
vor 8 Jahren
Abrufe

1 Einführung in Javadoc Johannes Rinn

2 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

3 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

Es können auch weitere Dateien eingebunden werden.

4 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

Dateien: Quellcodedateien Package Bemerkungen Overview

5 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

6 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

Doc Comments werden als HTML ausgelesen, weshalb HTML Syntax

7 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

public int x The horizontal and vertical distances of point (x,y) public

8 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

Diese Datei muss in das Verzeichnis des Packages abgelegt werden. Die Datei package.

9 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

Entscheidend ist auch hier was zwischen <body> </body> steht.

10 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

Diese Dateien müssen in einem Verzeichnis unterhalb des Packages abgelegt sein, welches../doc-files/ heißen muss.

11 Javadoc Tags Es gibt spezielle Schlüsselwörter welche als Tags bezeichnet werden. Tags werden mit einem gekennzeichnet. Übersicht über mögliche Tags: author deprecated docroot exception inheritdoc link linkplain param return see serial serialdata serialfield since throws value version Dokumentieren mit Javadoc 11

Übersicht über mögliche Tags: author deprecated docroot exception inheritdoc link

12 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. /** As of JDK 1.1, replaced by {@link #setbounds(int,int,int,int)} */ Dokumentieren mit Javadoc 12

13 Wo können welche Javadoc Tags benutzt werden? Klasse, Interface Datentypen Konstruktor, Methoden Dokumentieren mit Javadoc 13

Package Overview @see @since @author @version

14 Klasse, Interface Datentypen Konstruktor, Methoden @inheritdoc Dokumentieren mit Javadoc 14

@serialdata @serialfield @link @linkplain

15 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"> * Johannes Rinn 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

jpg"> * * @author Johannes Rinn * @version 1.0 */ public class Auto { /** Legt eine neue Datei an.

16 /** * Ein neues Auto wird angelegt. * <br>der Konstruktor ruft die Funktion sichereauto() auf, und * das Auto wird gespeichert * Name Der Name des Autos. 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

Name des Autos. * @param AnzahlGaenge Die Anzahl der Gänge des Fahrzeuges.

17 /** * 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. * Gaenge gibt die Anzahl der Gänge des Autos an. Autoname gibt den Namen des Autos an. IOExeption wird geworfen wenn nicht in die Datei geschreiben werden kann. 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

* @return true - wenn das Auto in einer Datei abgespeichert werden konnte.

18 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

Die Packages motorbetrieben und nichtmotorbetrieben haben ein Verzeichnis doc-files in welchem zusätzliche Dateien

19 Der Aufruf von Javadoc kann über die Konsole aber auch über Compiler wie Eclipse erfolgen. Dokumentieren mit Javadoc 19

20 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

Außerdem kann ausgewählt werden, ob Inhalte die private

21 Dokumentieren mit Javadoc 21

22 Ausgabe: Dokumentieren mit Javadoc 22

23 Dokumentieren mit Javadoc 23

24 Dokumentieren mit Javadoc 24

25 Dokumentieren mit Javadoc 25

26 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 ML Dokumentieren mit Javadoc 26

27 Ähnliche Werkzeuge die zur Dokumentation benutzt werden können: Doxygen erstellt Dokumentationen für C++, C, IDL, Java und C# Doc++ erstellt Dokumentationen für C, C++, IDL und Java Dokumentieren mit Javadoc 27

28 Weitere Informationen finden Sie bei: How to Write Doc Comments for the Javadoc Tool Dokumentieren mit Javadoc 28

Ähnliche Dokumente

Javadoc. Programmiermethodik. Eva Zangerle Universität Innsbruck

Javadoc. Programmiermethodik. Eva Zangerle Universität Innsbruck Javadoc Programmiermethodik Eva Zangerle Universität Innsbruck Überblick Einführung Java Ein erster Überblick Objektorientierung Vererbung und Polymorphismus Ausnahmebehandlung Pakete und Javadoc Spezielle