Referat T13 Javadoc

1.223 Aufrufe

Veröffentlicht am

Veröffentlicht in: Technologie
0 Kommentare
0 Gefällt mir
Statistik
Notizen
  • Als Erste(r) kommentieren

  • Gehören Sie zu den Ersten, denen das gefällt!

Keine Downloads
Aufrufe
Aufrufe insgesamt
1.223
Auf SlideShare
0
Aus Einbettungen
0
Anzahl an Einbettungen
39
Aktionen
Geteilt
0
Downloads
11
Kommentare
0
Gefällt mir
0
Einbettungen 0
Keine Einbettungen

Keine Notizen für die Folie

Referat T13 Javadoc

  1. 1. Tags, Overview-Seiten, Stil- Konventionen, Erzeugen der HTML Dokumentation von Hand und durch Ant LMU - Softwareentwicklungspraktikum WS09/10 - V17
  2. 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. 3. Ziel: Beschreibung muss so detailliert sein, dass man eine Methode nur anhand der Beschreibung implementieren kann LMU - Softwareentwicklungspraktikum WS09/10 - V17 3
  4. 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. 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. 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. 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. 8. • Unabhängig von Implementierung • Kommentare werden vererbt, wenn nicht überschrieben LMU - Softwareentwicklungspraktikum WS09/10 - V17 8
  9. 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.&nbsp;Bauers Melkalgorithmus */ /** Simulation von Dr.<!-- --> Bauers Melkalgorithmus */ LMU - Softwareentwicklungspraktikum WS09/10 - V17 9
  10. 10. /** * Berechnet das Quadrat einer Zahl. * Gibt die berechnete Zahl zur&uuml;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
  11. 11. • Schlüssbegriffe mit <code> … </code> - Java Keywords - Package Namen - Klassen - Methoden - Objektvariablen - Interfaces - Parameter - (Code Beispiele, extern!) LMU - Softwareentwicklungspraktikum WS09/10 - V17 11
  12. 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. 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. 14. • @author – erzeugt einen Autoreneintrag – chronologische Reihenfolge • @version – trägt die Version ein – Beispielformat: mm/dd/yy LMU - Softwareentwicklungspraktikum WS09/10 - V17 14
  15. 15. /** * EinfacheMathematik stellt * einfache mathematische Ope- * rationen zur Verf&uuml;gung. * * @author Sven Osterwald * @version 11/12/09 */ public class EinfacheMathematik { //... } LMU - Softwareentwicklungspraktikum WS09/10 - V17 15
  16. 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. 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. 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. 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
  20. 20. • @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 LMU - Softwareentwicklungspraktikum WS09/10 - V17 20
  21. 21. /** * Beispiele für Verweise in javadoc * * @see #faktor * @see #EinfacheMathematik() * @see #produkt(int, int, boolean) * @see EinfacheMathematik */ LMU - Softwareentwicklungspraktikum WS09/10 - V17 21
  22. 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. 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. 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. 25. • Dokumentationen werden package-spezifisch in Unterverzeichnissen abgelegt LMU - Softwareentwicklungspraktikum WS09/10 - V17 25
  26. 26. LMU - Softwareentwicklungspraktikum WS09/10 - V17 26
  27. 27. • Eclipse bringt einen eigenen Assistenten zum Erstellen von Javadoc mit Project » Generate Javadoc… LMU - Softwareentwicklungspraktikum WS09/10 - V17 27
  28. 28. Pfad zu javadoc.exe des Java JDK Quelldateien Zielordner LMU - Softwareentwicklungspraktikum WS09/10 - V17 28
  29. 29. Titel Ausgabe-Optionen LMU - Softwareentwicklungspraktikum WS09/10 - V17 29
  30. 30. zusätzliche Parameter des javadoc-Befehls LMU - Softwareentwicklungspraktikum WS09/10 - V17 30
  31. 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
  32. 32. <javadoc sourcepath="src" Quelle, Ziel, einzubeziehende destdir="doc" packagesnames="lib,gui,cli" Packages access="public" Sichtbarkeitslevel der doctitle="Game Of Life - V17" Methoden author="true" use="true" nodeprecated="false" Aussehen nodeprecatedlist="false" noindex="false" nonavbar="false" notree="false" splitindex="true" use="true" version="true"/> LMU - Softwareentwicklungspraktikum WS09/10 - V17 32
  33. 33. … oder einfacher mit Eclipse: Javadoc Assistent 3/3 LMU - Softwareentwicklungspraktikum WS09/10 - V17 33
  34. 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

×