Puppet - Module entwickeln - Von der Planung bis zur Umsetzung
Referat T13 Javadoc
1. Tags, Overview-Seiten, Stil-
Konventionen, Erzeugen der HTML
Dokumentation von Hand und durch
Ant
LMU - Softwareentwicklungspraktikum WS09/10 - V17
2. • 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
3. Ziel:
Beschreibung muss so detailliert
sein, dass man eine Methode nur
anhand der Beschreibung
implementieren kann
LMU - Softwareentwicklungspraktikum WS09/10 - V17 3
4. • 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
LMU - Softwareentwicklungspraktikum WS09/10 - V17 4
5. • In Java geschrieben
• Interpretiert javadoc Kommentare vor
Methoden, Klassen, Interfaces, Klassenvariablen
/** … */
• HTML Syntax für Links, Bilder, Format, etc.
LMU - Softwareentwicklungspraktikum WS09/10 - V17 5
6. • 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>
LMU - Softwareentwicklungspraktikum WS09/10 - V17 6
7. • 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 */
LMU - Softwareentwicklungspraktikum WS09/10 - V17 7
8. • Unabhängig von Implementierung
• Kommentare werden vererbt, wenn nicht
überschrieben
LMU - Softwareentwicklungspraktikum WS09/10 - V17 8
9. • 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 */
LMU - Softwareentwicklungspraktikum WS09/10 - V17 9
10. /**
* 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
LMU - Softwareentwicklungspraktikum WS09/10 - V17 10
12. • 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
LMU - Softwareentwicklungspraktikum WS09/10 - V17 12
13. 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
LMU - Softwareentwicklungspraktikum WS09/10 - V17 13
14. • @author
– erzeugt einen Autoreneintrag
– chronologische Reihenfolge
• @version
– trägt die Version ein
– Beispielformat: mm/dd/yy
LMU - Softwareentwicklungspraktikum WS09/10 - V17 14
15. /**
* EinfacheMathematik stellt
* einfache mathematische Ope-
* rationen zur Verfügung.
*
* @author Sven Osterwald
* @version 11/12/09
*/
public class EinfacheMathematik
{
//...
}
LMU - Softwareentwicklungspraktikum WS09/10 - V17 15
16. • @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
17. /**
* 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;
}
LMU - Softwareentwicklungspraktikum WS09/10 - V17 17
18. • @throws
– Beschreibung einer möglichen Exception
– identisch mit @exception
• @deprecated
– veraltete Methode
– Angabe der Version, in der Methode entfernt
wurde
– Verweis auf neue Methode
LMU - Softwareentwicklungspraktikum WS09/10 - V17 18
19. /**
* 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...
}
LMU - Softwareentwicklungspraktikum WS09/10 - V17 19
22. • 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
LMU - Softwareentwicklungspraktikum WS09/10 - V17 22
23. • 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
LMU - Softwareentwicklungspraktikum WS09/10 - V17 23
24. 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.
LMU - Softwareentwicklungspraktikum WS09/10 - V17 24
25. • Dokumentationen werden
package-spezifisch in
Unterverzeichnissen
abgelegt
LMU - Softwareentwicklungspraktikum WS09/10 - V17 25
27. • Eclipse bringt einen eigenen Assistenten zum
Erstellen von Javadoc mit
Project » Generate Javadoc…
LMU - Softwareentwicklungspraktikum WS09/10 - V17 27
28. Pfad zu javadoc.exe des
Java JDK
Quelldateien
Zielordner
LMU - Softwareentwicklungspraktikum WS09/10 - V17 28
29. Titel
Ausgabe-Optionen
LMU - Softwareentwicklungspraktikum WS09/10 - V17 29
31. • ANT kann über die build.xml ebenfalls
Javadoc generieren
• Tag dazu heißt javadoc und bietet ähnliche
Möglichkeiten wie die Kommandozeile
LMU - Softwareentwicklungspraktikum WS09/10 - V17 31
33. … oder einfacher mit Eclipse:
Javadoc Assistent 3/3
LMU - Softwareentwicklungspraktikum WS09/10 - V17 33
34. 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