Referat T13 Javadoc

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

LMU - 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)
{ Aussagekräftiger Namen
z = z + 2*y + 1;

}
y = y + 1; Beschreibung
return z;
}

LMU - Softwareentwicklungspraktikum WS09/10 - V17 2

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

Lösung:
/** Simulation von Dr. Bauers Melkalgorithmus */
/** 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; Aussagekräftiger Namen
while (y != a)
{ Beschreibung
z = z + 2*y + 1;

}
y = y + 1;
Alles vorhanden für
}
return z;
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 name Parameterbeschreibung Methode
description
@return description Beschreibung des return- Methode
Werts
@exception classname Beschreibung einer Methode
description Ausnahme
@see reference Querverweis Klasse, Interface,
Instanzvariable, Methode
@deprecated veraltete Methode Methode
description


• @author
– erzeugt einen Autoreneintrag
– chronologische Reihenfolge

• @version
– trägt die Version ein
– Beispielformat: mm/dd/yy


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


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


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


• 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 Überblick
javadoc *.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.

• Dokumentationen werden
package-spezifisch in
Unterverzeichnissen
abgelegt


• Eclipse bringt einen eigenen Assistenten zum
Erstellen von Javadoc mit

Project » Generate Javadoc…


Pfad zu javadoc.exe des
Java JDK

Quelldateien

Zielordner


Titel
Ausgabe-Optionen


zusätzliche Parameter des
javadoc-Befehls


• ANT kann über die build.xml ebenfalls
Javadoc generieren
• Tag dazu heißt javadoc und bietet ähnliche
Möglichkeiten wie die Kommandozeile


… oder einfacher mit Eclipse:

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

Referat T13 Javadoc

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (11)

En vedette

En vedette (6)

Similaire à Referat T13 Javadoc

Similaire à Referat T13 Javadoc (20)

Referat T13 Javadoc