• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
Referat T13 Javadoc
 

Referat T13 Javadoc

on

  • 1,330 views

 

Statistics

Views

Total Views
1,330
Views on SlideShare
1,296
Embed Views
34

Actions

Likes
0
Downloads
6
Comments
0

2 Embeds 34

http://www.dbs.ifi.lmu.de 29
http://www.slideshare.net 5

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

    Referat T13 Javadoc Referat T13 Javadoc Presentation Transcript

    • 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 LMU - Softwareentwicklungspraktikum WS09/10 - V17 3
    • • 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
    • • 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
    • • 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
    • • 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
    • • Unabhängig von Implementierung • Kommentare werden vererbt, wenn nicht überschrieben LMU - Softwareentwicklungspraktikum WS09/10 - V17 8
    • • 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
    • /** * 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
    • • Schlüssbegriffe mit <code> … </code> - Java Keywords - Package Namen - Klassen - Methoden - Objektvariablen - Interfaces - Parameter - (Code Beispiele, extern!) LMU - Softwareentwicklungspraktikum WS09/10 - V17 11
    • • 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
    • 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
    • • @author – erzeugt einen Autoreneintrag – chronologische Reihenfolge • @version – trägt die Version ein – Beispielformat: mm/dd/yy LMU - Softwareentwicklungspraktikum WS09/10 - V17 14
    • /** * 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
    • • @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; } LMU - Softwareentwicklungspraktikum WS09/10 - V17 17
    • • @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
    • /** * 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
    • • @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
    • /** * Beispiele für Verweise in javadoc * * @see #faktor * @see #EinfacheMathematik() * @see #produkt(int, int, boolean) * @see EinfacheMathematik */ LMU - Softwareentwicklungspraktikum WS09/10 - V17 21
    • • 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
    • • 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
    • 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
    • • Dokumentationen werden package-spezifisch in Unterverzeichnissen abgelegt LMU - Softwareentwicklungspraktikum WS09/10 - V17 25
    • LMU - Softwareentwicklungspraktikum WS09/10 - V17 26
    • • Eclipse bringt einen eigenen Assistenten zum Erstellen von Javadoc mit Project » Generate Javadoc… LMU - Softwareentwicklungspraktikum WS09/10 - V17 27
    • Pfad zu javadoc.exe des Java JDK Quelldateien Zielordner LMU - Softwareentwicklungspraktikum WS09/10 - V17 28
    • Titel Ausgabe-Optionen LMU - Softwareentwicklungspraktikum WS09/10 - V17 29
    • zusätzliche Parameter des javadoc-Befehls LMU - Softwareentwicklungspraktikum WS09/10 - V17 30
    • • 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
    • <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
    • … oder einfacher mit Eclipse: Javadoc Assistent 3/3 LMU - Softwareentwicklungspraktikum WS09/10 - V17 33
    • 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