Referat T13 Javadoc

Tags, Overview-Seiten, Stil-Konventionen, Erzeugen der HTML Dokumentation von Hand und durch Ant

LMU - Softwareentwicklungspraktikum WS09/10 - V17

2LMU - Softwareentwicklungspraktikum WS09/10 - V17

• Viele Programmierer an großem Projekt

• Immer komplexere Klassen

public static int ichMacheWasTolles(int a)

{

int y = 0;

int z = 0;

while (y != a)

{

z = z + 2*y + 1;

y = y + 1;

}

return z;

}

Aussagekräftiger Namen

Beschreibung


Ziel:

Beschreibung muss so detailliert sein, dass man eine Methode nur

anhand der Beschreibung implementieren kann


• Programm macht genau das, was in Beschreibung steht

• Vertrag zwischen Benutzer der API und der Implementierung

• Beschreibung unabhängig von Implementierung

• Kein Beispielcode in Beschreibung verlinken


• In Java geschrieben

• Interpretiert javadoc Kommentare vor Methoden, Klassen, Interfaces, Klassenvariablen

/** … */

• HTML Syntax für Links, Bilder, Format, etc.


• Zeilen bündig mit Code

• Erste Zeile: /**

• Jede Zeile beginnt mit: * (optional, aber schön)

• Erster Satz ist Beschreibung in Übersicht

• {@link KlassenName} Link zu Klasse

• Paragraphen mit <p> … </p>


• Zeilenumbrüche nicht automatisch: Für Ausgabe mit <br>, in Code nach 80 Zeichen

• Sonderzeichen HTML maskiert

• Auf Beschreibung folgt Leerzeile

• Erste Zeile, welche mit @ beginnt: Ende der Beschreibung

• Letzte Zeile schließt Kommentar mit */


• Unabhängig von Implementierung

• Kommentare werden vererbt, wenn nicht überschrieben


• Kurze, vollständige Zusammenfassung der Methode / Klasse / Interface, erscheint auf Übersichtsseiten

• Beginnt mit beschreibendem Verb

• Unterschied bei überladenen Methoden klarstellen

• Ende des Satzes ist bei Punkt mit Leerzeichen

/** Simulation von Dr. Bauers Melkalgorithmus */

/** Simulation von Dr. Bauers Melkalgorithmus */

Lösung:

/** Simulation von Dr. Bauers Melkalgorithmus */


/**

* Berechnet das Quadrat einer Zahl.

* Gibt die berechnete Zahl zurück.

*

* @param a

* @return

*/

public static int quadrat(int a)

{

int y = 0;

int z = 0;

while (y != a)

{

z = z + 2*y + 1;

y = y + 1;

}

return z;

}

Aussagekräftiger Namen

Beschreibung

Alles vorhanden für andere Implementierung


• Schlüssbegriffe mit <code> … </code>- Java Keywords

- Package Namen

- Klassen

- Methoden

- Objektvariablen

- Interfaces

- Parameter

- (Code Beispiele, extern!)


• Inline {@link} Links bedacht nutzen, nur einmal pro API Verweis

• prägnant, nicht zwingend vollständige Sätze

• 3. Person

• Abkürzungen vermeiden

• Beschreibung zusätzlich zum aussagekräftigen Methodennamen


Tag & Parameter Ausgabe Verwendung

@author name Autoreneintrag Klasse, Interface

@version version Versionseintrag Klasse, Interface

@param namedescription

Parameterbeschreibung Methode

@return description Beschreibung des return-Werts

Methode

@exception classnamedescription

Beschreibung einer Ausnahme

Methode

@see reference Querverweis Klasse, Interface, Instanzvariable, Methode

@deprecated

descriptionveraltete Methode Methode

13


• @author

– erzeugt einen Autoreneintrag

– chronologische Reihenfolge

• @version

– trägt die Version ein

– Beispielformat: mm/dd/yy

14

LMU - Softwareentwicklungspraktikum WS09/10 - V17 15

/**

* EinfacheMathematik stellt

* einfache mathematische Ope-

* rationen zur Verfügung.

*

* @author Sven Osterwald

* @version 11/12/09

*/

public class EinfacheMathematik

{

//...

}

• @param

– Parameterbeschreibung

– gleiche Reihenfolge wie Methodendeklaration

– Name des Parameters, nicht den Typ!

• @return

– beschreibt Rückgabewert

– nötig in allen Methoden mit Rückgabewert

• vgl. Eclipse-Hilfseinblendungen

16


/**

* Berechnet das Produkt zweier Werte.

*

* @param a erster Faktor

* @param b zweiter Faktor

* @param print Ausgabe des Produkts?

* @return Produkt zweier Faktoren

*/

public int produkt(int a, int b,

boolean print) {

int c = a * b;

if(print) {

System.out.println(

a+" + "+b+" = "+c);

}

return c;

}


• @throws

– Beschreibung einer möglichen Exception

– identisch mit @exception

• @deprecated

– veraltete Methode

– Angabe der Version, in der Methode entfernt wurde

– Verweis auf neue Methode

18


/**

* Berechnet das Produkt zweier Werte.

*

* @throws IllegalArgumentException falls Argumente falsch sind

* @deprecated ersetzt seit Version 11/12/09 durch

* {@link #produkt(int, int, boolean)}

*/

public void produkt() throws IllegalArgumentException {

//berechne das Produkt...

}


• @see

– Verweis innerhalb der Dokumentation

– möglich auf Instanzvariablen, Konstruktoren, Methoden, Klassen, Packages

– Beispiele: • @see #variable

• @see #Konstruktor(Typ)

• @see #methode(Typ, Typ)

• @see Klasse

• @see Klasse#methode(Typ)

• @see package.Klasse

20


/**

* Beispiele für Verweise in javadoc

*

* @see #faktor

* @see #EinfacheMathematik()

* @see #produkt(int, int, boolean)

* @see EinfacheMathematik

*/


• Die Dokumentation von Packages beschreibt dessen gesamten Inhalt und Zweck und ist daher meist umfangreicher

• Beinhaltet die logische Zusammenfassung und Gruppierung der einzelnen Klassen und Interfaces

• Verweist auf andere Java-Elemente, die in Zusammenhang mit diesem Programm wichtig sind

22

• Packages werden gesondert in einer eignen package.html dokumentiert

• Nutzen von Java-Tags und HTML möglich

• Erster Satz im <body>- Bereich wird für die Übersicht genutzt

• Eine Beispiel-Package-Dokumentation ist auf der Webseite verlinkt



javadoc

• Die Dokumentation kann über die Kommandozeile mit dem Befehl javadoc<parameter> erzeugt werden

• Die wichtigsten Konfigurationen im Überblickjavadoc *.java

Erzeugt Javadoc für alle .java-Dateien im gleichen Verzeichnis

javadoc –d doc\ *.java

Erzeugt Javadoc im Unterordner doc/

javadoc –public *.java

Nur Elemente, die als public gekennzeichnet sind, werden bei der Dokumentation berücksichtigt.

24


• Dokumentationen werden package-spezifisch in Unterverzeichnissen abgelegt

25



• Eclipse bringt einen eigenen Assistenten zum Erstellen von Javadoc mit

27

Project » Generate Javadoc…


Quelldateien

28

Zielordner

Pfad zu javadoc.exe des

Java JDK


Titel

Ausgabe-Optionen

29


zusätzliche Parameter des javadoc-Befehls

30


• ANT kann über die build.xml ebenfalls Javadoc generieren

• Tag dazu heißt javadoc und bietet ähnliche Möglichkeiten wie die Kommandozeile

31


<javadoc

sourcepath="src"

destdir="doc"

packagesnames="lib,gui,cli"

access="public"

doctitle="Game Of Life - V17"

author="true"

use="true"

nodeprecated="false"

nodeprecatedlist="false"

noindex="false"

nonavbar="false"

notree="false"

splitindex="true"

use="true"

version="true"/>

Quelle, Ziel, einzubeziehende Packages

32

Sichtbarkeitslevel der Methoden

Aussehen


… oder einfacher mit Eclipse:

33

Javadoc Assistent 3/3

Weitere Infos findet ihr unter:

http://www.dbs.ifi.lmu.de/Lehre/SEP/WS0910/

gruppen/sep0910/v/V17/

Gruppe V17:

Frederik Brudy, Sven Osterwald, Max Kleucker

Technology

Referat T13 Javadoc