Die Präsentation wird geladen. Bitte warten

Die Präsentation wird geladen. Bitte warten

Dokumentierwerkzeuge Eine Seminararbeit im Rahmen der LVA Programmierstil erstellt von Severin Forstinger.

Ähnliche Präsentationen


Präsentation zum Thema: "Dokumentierwerkzeuge Eine Seminararbeit im Rahmen der LVA Programmierstil erstellt von Severin Forstinger."—  Präsentation transkript:

1 Dokumentierwerkzeuge Eine Seminararbeit im Rahmen der LVA Programmierstil erstellt von Severin Forstinger

2 Severin Forstinger2 Gliederung des Vortrags Einleitung & Motivation Einleitung & Motivation Praktische Beispiele Praktische Beispiele –JavaDoc –CSC (C#-Tool) –Doxygen –Weiterführende Links Zusammenfassung Zusammenfassung Anmerkungen Anmerkungen Weiterführende Informationen Weiterführende Informationen

3 Severin Forstinger3 Einleitung Tools schon länger bekannt Tools schon länger bekannt –Firmenintern –Speziallösungen (Preis!) –Selbst gestrickt Keine Normen vorhanden Keine Normen vorhanden Wurde bald als wichtig erkannt Wurde bald als wichtig erkannt

4 Severin Forstinger4 Motivation Firmenseitig Firmenseitig –Neue Module haben konsistentes API- Layout (vgl. Java) –Anreiz zum Einsatz des Produkts Programmiererseitig Programmiererseitig –Muss nicht zwischen Programmier- & Dokumentationswerkzeug wechseln –Dokumentation geht neben Codeentwurf » verliert nicht den Faden » vergisst kaum, etwas zu beschreiben

5 Severin Forstinger5 Praktische Beispiele Aus der Fülle an Tools drei ausgewählt Aus der Fülle an Tools drei ausgewählt –Javadoc (da sehr bekannt und erprobt) –CSC (C#, da eine Neuerung) –Doxygen (als Vertreter von produktfremden Werkzeugen) Alleine Javadoc im Detail würde einen Vortrag füllen Alleine Javadoc im Detail würde einen Vortrag füllen

6 Severin Forstinger6 Javadoc (1/10) Anfangs bei Sun intern verwendet Anfangs bei Sun intern verwendet Bald als Tool im JDK enthalten Bald als Tool im JDK enthalten Erzeugt HTML-Dateien Erzeugt HTML-Dateien Möglich für: Möglich für: –Source Code.java (class, interface, field, constructor, method comments) –Package comment files (package.html) –Overview comment files –Div. Files (als Refernenzziel)

7 Severin Forstinger7 Javadoc (2/10) Beginnt mit /** und endet mit */ Beginnt mit /** und endet mit */ Dazwischen HTML (jeder HTML-Tag ist gültig) mit speziellen Javadoc-Tags Dazwischen HTML (jeder HTML-Tag ist gültig) mit speziellen Javadoc-Tags Muss vor einer class, field, constructor oder method declaration stehen Muss vor einer class, field, constructor oder method declaration stehen 2 Teile: 2 Teile: –Description (Beschreibung bis –Tag-list (Liste aller Standalone-Tags)

8 Severin Forstinger8 Javadoc (3/10) Tags Tags –Standalone: können nur in der Tag-list verwendet werden –Inline: können überall im Doc-Kommentar eingesetzt werden Notation: –Custom: können über die Kommandozeile spezifiziert werden

9 Severin Forstinger9 Javadoc (4/10) /** As of JDK 1.1, replaced by #setBounds(int,int,int,int)} As of JDK 1.1, replaced by #setBounds(int,int,int,int)}*/ Dabei ist ein Standalone-Tag #setBounds(int,int,int,int)} ein Inline- Tag

10 Severin Forstinger10 Javadoc (5/10) /** * Ist eine Testmethode ohne tieferen Sinn. * Ist eine Testmethode ohne tieferen Sinn. * Der Methode wird ein String übergeben, der dann * Der Methode wird ein String übergeben, der dann * ausgegeben wird. * ausgegeben wird. * str ein String, der ausgegeben werden soll str ein String, der ausgegeben werden soll*/ public void writeText(String str) { System.out.println(str);}

11 Severin Forstinger11 Javadoc (6/10) Erste Zeile wird als Zusammenfassung interpretiert Erste Zeile wird als Zusammenfassung interpretiert –Wird in den Index kopiert –Wird in der summary-table eingetragen Erste Zeile endet mit dem ersten. Erste Zeile endet mit dem ersten. –Problem: * this is Prof. Knuths mix. –Lösung: HTML Tag dahinter einfügen * this is Prof. Knuths mix. oder* this is Prof. Knuths mix.

12 Severin Forstinger12 Javadoc (7/10) Die erzeugte Ausgabe schaut so aus: Java-Ausgabe Die erzeugte Ausgabe schaut so aus: Java-Ausgabe Java-Ausgabe Anmerkungen Anmerkungen –Seit Javadoc 1.4 ist das * am Beginn jeder Zeile nicht mehr nötig. –/** und */ sollten in einer eigenen Zeile stehen –Zwischen der Beschreibung und der Tag- Liste soll eine Leerzeile eingefügt werden

13 Severin Forstinger13 Javadoc (8/10) Besonderheiten Besonderheiten –Es gibt pro Doc-Kommentar nur eine Beschreibung die beim endet. Sie kann danach nicht mehr fortgesetzt werden. –Parameter werden nicht automatisch dokumentiert, es ist für jeden nötig. –Mit einem Return-Wert ist es ebenso, dieser wird festgelegt.

14 Severin Forstinger14 Javadoc (9/10) Package-level Kommentare Package-level Kommentare –Werden in einer Datei package.html geschrieben (inline-tags können verwendet werden) –Diese Datei wird in das Package- Verzeichnis kopiert (zu den.java-Dateien) –Javadoc sucht nach dieser Datei und kopiert den Inhalt in den Package- Description Abschnitt –Erste Zeile kommt in die Overview- Summary

15 Severin Forstinger15 Javadoc (10/10) Liste aller Tags ist in meinem Projektbericht, bzw. unter Liste aller Tags ist in meinem Projektbericht, bzw. unter Aufruf über javadoc.exe (in jdk\bin) Aufruf über javadoc.exe (in jdk\bin) –Hat eine Fülle von Parametern (56 Stück) –Oft muss über ein Makefile gearbeitet werden, da sonst die Eingabe zu lang wird (z.B. DOS) Ein lustiges Beispiel sowie alle Parameter findet man hier:

16 Severin Forstinger16 CSC (1/6) Im C# Compiler integriert, daher nur für C# verwendbar Im C# Compiler integriert, daher nur für C# verwendbar Bildet XML-Dateien (Kategorie+Daten) Bildet XML-Dateien (Kategorie+Daten) Alle XML-Tags gültig, aber nur wenige haben spezielle Bedeutung Alle XML-Tags gültig, aber nur wenige haben spezielle Bedeutung Erzeugt keine formatierte Ausgabe wie Javadoc Erzeugt keine formatierte Ausgabe wie Javadoc

17 Severin Forstinger17 CSC (2/6) Beginnt mit /// Beginnt mit /// –Dieser Kommentar ist nur einzeilig, daher muss /// vor jeder Zeile wiederholt werden. –Muss vor dem zugehörigen Objekt stehen. –Jeder gültige XML-Tag wird verarbeitet. Erste Zeile hat keine spezielle Bedeutung Erste Zeile hat keine spezielle Bedeutung Generierter Output wird in ein XML- Dokument gespeichert Generierter Output wird in ein XML- Dokument gespeichert

18 Severin Forstinger18 CSC (3/6) /// text for class MyClass public class MyClass { /// Used to indicate status. public static void MyMethod(int Int1) { } /// text for Main public static void Main () { } }

19 Severin Forstinger19 CSC (4/6) Project2 Project2 text for class MyClass text for class MyClass Used to indicate status. Used to indicate status. text for Main text for Main

20 Severin Forstinger20 CSC (5/6) Automatische Doc-Generierung Automatische Doc-Generierung –Über Kommandozeile einstellbar (/doc:file) –Über Compileroption (Build-Optionen) Betrachtungsfähige Ausgabe: Betrachtungsfähige Ausgabe: –Über Befehl im Programm möglich –Unter Tools, Build Comment Web Page –Erzeugt mehrere HTM-Dateien, die die Struktur des Projekts bzw. der Solution generiert (ähnlich dem Aussehen von Javadoc)

21 Severin Forstinger21 CSC (6/6) Liste aller besonderen XML-Tags findet man in der VS.NET Hilfe, bzw. in meinem Projektbericht Liste aller besonderen XML-Tags findet man in der VS.NET Hilfe, bzw. in meinem Projektbericht –Es gibt 18 Stück –Manche werden vom Compiler überprüft (z.B. ob der angegebene Parameter tatsächlich existiert) Tags im Grunde nicht eingeschränkt, da alle gültigen XML-Tags erlaubt sind Tags im Grunde nicht eingeschränkt, da alle gültigen XML-Tags erlaubt sind

22 Severin Forstinger22 Doxygen (1/5) Ist von einem Programmierer entwickelt worden, weil er spezielle Fähigkeiten des Tools benötigte Ist von einem Programmierer entwickelt worden, weil er spezielle Fähigkeiten des Tools benötigte –Unterstützt C, C++, C#, Java, PHP, IDL –Mögliche Ausgabeformate sind HTML, XML, RTF, Latex, PDF, PS, Unix-Manpage –Für C++ kann man Vererbungsdiagramme generieren (bei Mehrfachvererbung sehr nützlich)

23 Severin Forstinger23 Doxygen (2/5) Wurde unter Linux entwickelt Wurde unter Linux entwickelt Portiert für: Unix, Windows, Solaris Portiert für: Unix, Windows, Solaris Doxygen ist sehr mächtig, aber dadurch auch sehr kompliziert Doxygen ist sehr mächtig, aber dadurch auch sehr kompliziert –Knapp Optionen die man bei der Generierung angeben kann –Sehr unübersichtliche Oberfläche (siehe Screenshot im Projektbericht)

24 Severin Forstinger24 Doxygen (3/5) Mehrere Arten von Kommentarbezeichnern Mehrere Arten von Kommentarbezeichnern –Java /**... */ –C(#/++)///(in jeder Zeile) –Qt-Format Java/*!... */ –Qt-Format C(#/++)//!(in jeder Zeile) Anders als in Javadoc muss vor jedem Parameter stehen Anders als in Javadoc muss vor jedem Parameter stehen

25 Severin Forstinger25 Doxygen (4/5) Tags entweder im Java-Stil Tags entweder im Java-Stil Doxygen eigenes Format \tag Doxygen eigenes Format \tag JavadocDoxygen /** * A test discription. * A test discription. var1 a simple varibale var1 a simple varibale * var2 another one * var2 another one * A test discription. * A test discription. var1 a simple varibale var1 a simple varibale var2 another one var2 another one

26 Severin Forstinger26 Doxygen (5/5) Hat eine Menge spezieller Tags (z.B. Gruppierung – in Javadoc über Cmd) Hat eine Menge spezieller Tags (z.B. Gruppierung – in Javadoc über Cmd) Besonderheiten Besonderheiten –Kann Latexformeln generieren (wenn Latex installiert ist) –Über ein Plugin (Link auf der Doxygen- Homepage) können auch umfangreicherer Diagramme erstellt werden Sehr komplex – Manual hat 120 Seiten! Sehr komplex – Manual hat 120 Seiten!

27 Severin Forstinger27 Zusammenfassung (1/2) Javadoc Javadoc +Für Java bestens geeignet +Langer Praxiseinsatz -Umständlich auszuführen CSC CSC +Im Compiler integriert +Sehr flexibel –Noch in den Kinderschuhen –Zusatztool notwendig

28 Severin Forstinger28 Zusammenfassung (2/2) Doxygen Doxygen +Für viele Produkte geeignet +Viele Zusatzfunktionen ±Sehr umfangreich –Umständlich sich einzuarbeiten Allgemein Allgemein –Alles in allem schon sehr viel Funktionalität –Sehr nützlich und nötig –Wird noch intensiver werden

29 Severin Forstinger29 Anmerkungen Tools schon sehr brauchbar Tools schon sehr brauchbar Eher eine Hilfe für den Programmierer selbst Eher eine Hilfe für den Programmierer selbst Generierte Version hat wenig mit einer endgültigen Dokumentation zu tun, eher nur ein Grundgerüst Generierte Version hat wenig mit einer endgültigen Dokumentation zu tun, eher nur ein Grundgerüst

30 Severin Forstinger30 Weiterführende Infos Einen guten Einstieg in die Thematik findet man unter folgenden Links: Einen guten Einstieg in die Thematik findet man unter folgenden Links: – – – – – –


Herunterladen ppt "Dokumentierwerkzeuge Eine Seminararbeit im Rahmen der LVA Programmierstil erstellt von Severin Forstinger."

Ähnliche Präsentationen


Google-Anzeigen