Your SlideShare is downloading. ×
Referat T13 Javadoc
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

Referat T13 Javadoc

913

Published on

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
913
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
7
Comments
0
Likes
0
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 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.&nbsp;Bauers Melkalgorithmus */ /** Simulation von Dr.<!-- --> Bauers Melkalgorithmus */ LMU - Softwareentwicklungspraktikum WS09/10 - V17 9
  • 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. • Schlüssbegriffe mit <code> … </code> - Java Keywords - Package Namen - Klassen - Methoden - Objektvariablen - Interfaces - Parameter - (Code Beispiele, extern!) LMU - Softwareentwicklungspraktikum WS09/10 - V17 11
  • 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&uuml;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
  • 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. /** * Beispiele für Verweise in javadoc * * @see #faktor * @see #EinfacheMathematik() * @see #produkt(int, int, boolean) * @see EinfacheMathematik */ LMU - Softwareentwicklungspraktikum WS09/10 - V17 21
  • 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
  • 26. LMU - Softwareentwicklungspraktikum WS09/10 - V17 26
  • 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
  • 30. zusätzliche Parameter des javadoc-Befehls LMU - Softwareentwicklungspraktikum WS09/10 - V17 30
  • 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. <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. … 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

×