Tags, Overview-Seiten, Stil-
             Konventionen, Erzeugen der HTML
             Dokumentation von Hand und durch
  ...
• Viele Programmierer an großem Projekt
• Immer komplexere Klassen
   public static int ichMacheWasTolles(int a)
   {
    ...
Ziel:
  Beschreibung muss so detailliert
  sein, dass man eine Methode nur
      anhand der Beschreibung
         implemen...
• Programm macht genau das, was in
  Beschreibung steht
• Vertrag zwischen Benutzer der API und der
  Implementierung
• Be...
• In Java geschrieben
• Interpretiert javadoc Kommentare vor
  Methoden, Klassen, Interfaces, Klassenvariablen
      /** …...
•    Zeilen bündig mit Code
•    Erste Zeile: /**
•    Jede Zeile beginnt mit: * (optional, aber schön)
•    Erster Satz i...
• Zeilenumbrüche nicht automatisch: Für
  Ausgabe mit <br>, in Code nach 80 Zeichen
• Sonderzeichen HTML maskiert
• Auf Be...
• Unabhängig von Implementierung
• Kommentare werden vererbt, wenn nicht
  überschrieben




LMU - Softwareentwicklungspra...
• Kurze, vollständige Zusammenfassung der
  Methode / Klasse / Interface, erscheint auf
  Übersichtsseiten
• Beginnt mit b...
/**
 * Berechnet das Quadrat einer Zahl.
 * Gibt die berechnete Zahl zur&uuml;ck.
 *
 * @param a
 * @return
 */
 public st...
• Schlüssbegriffe mit <code> … </code>
      -    Java Keywords
      -    Package Namen
      -    Klassen
      -    Met...
• Inline {@link} Links bedacht nutzen, nur einmal
  pro API Verweis
• prägnant, nicht zwingend vollständige Sätze
• 3. Per...
Tag & Parameter                         Ausgabe                    Verwendung
@author name                            Auto...
• @author
       – erzeugt einen Autoreneintrag
       – chronologische Reihenfolge


• @version
       – trägt die Versio...
/**
  * EinfacheMathematik stellt
  * einfache mathematische Ope-
  * rationen zur Verf&uuml;gung.
  *
  * @author Sven Os...
• @param
  – Parameterbeschreibung
  – gleiche Reihenfolge wie Methodendeklaration
  – Name des Parameters, nicht den Typ!...
/**
 * Berechnet das Produkt zweier Werte.
 *
 * @param a      erster Faktor
 * @param b      zweiter Faktor
 * @param pri...
• @throws
       – Beschreibung einer möglichen Exception
       – identisch mit @exception

• @deprecated
       – veralt...
/**
  * Berechnet das Produkt zweier Werte.
  *
  * @throws     IllegalArgumentException falls Argumente falsch sind
  * @...
• @see
       – Verweis innerhalb der Dokumentation
       – möglich auf Instanzvariablen, Konstruktoren, Methoden,
      ...
/**
 * Beispiele für Verweise in javadoc
 *
 * @see #faktor
 * @see #EinfacheMathematik()
 * @see #produkt(int, int, boole...
• Die Dokumentation von Packages beschreibt
  dessen gesamten Inhalt und Zweck und ist
  daher meist umfangreicher
• Beinh...
• Packages werden gesondert in einer eignen
  package.html dokumentiert
• Nutzen von Java-Tags und HTML möglich
• Erster S...
javadoc
• Die Dokumentation kann über die
  Kommandozeile mit dem Befehl javadoc
  <parameter> erzeugt werden
• Die wichti...
• Dokumentationen werden
                                                      package-spezifisch in
                     ...
LMU - Softwareentwicklungspraktikum WS09/10 - V17   26
• Eclipse bringt einen eigenen Assistenten zum
  Erstellen von Javadoc mit




                                           ...
Pfad zu javadoc.exe des
                                                    Java JDK

                                    ...
Titel
                                                    Ausgabe-Optionen




LMU - Softwareentwicklungspraktikum WS09/10...
zusätzliche Parameter des
                                                      javadoc-Befehls




LMU - Softwareentwickl...
• ANT kann über die build.xml ebenfalls
  Javadoc generieren
• Tag dazu heißt javadoc und bietet ähnliche
  Möglichkeiten ...
<javadoc
 sourcepath="src"                                   Quelle, Ziel, einzubeziehende
 destdir="doc"
 packagesnames="...
… oder einfacher mit Eclipse:




                                                    Javadoc Assistent 3/3



LMU - Softw...
Weitere Infos findet ihr unter:
     http://www.dbs.ifi.lmu.de/Lehre/SEP/WS0910/
     gruppen/sep0910/v/V17/

Gruppe V17:
...
Upcoming SlideShare
Loading in …5
×

Referat T13 Javadoc

1,023
-1

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
1,023
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
11
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

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

×