Dokumentierwerkzeuge

Präsentation zum Thema: "Dokumentierwerkzeuge"—  Präsentation transkript:

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

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

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

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

5 Praktische Beispiele 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 Severin Forstinger

6 Javadoc (1/10) Anfangs bei Sun intern verwendet
Bald als Tool im JDK enthalten Erzeugt HTML-Dateien 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) Severin Forstinger

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

8 Javadoc (3/10) 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 Severin Forstinger

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

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

11 Javadoc (6/10) Erste Zeile wird als Zusammenfassung interpretiert
Wird in den Index kopiert Wird in der summary-table eingetragen Erste Zeile endet mit dem ersten „.“ Problem: * this is Prof. Knuth‘s mix. Lösung: HTML Tag dahinter einfügen * this is Prof.  Knuth‘s mix. oder * this is Prof.<!-- --> Knuth‘s mix. Severin Forstinger

12 Javadoc (7/10) Die erzeugte Ausgabe schaut so aus: Java-Ausgabe
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 Severin Forstinger

13 Javadoc (8/10) 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. Severin Forstinger

14 Javadoc (9/10) 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 Severin Forstinger

15 Javadoc (10/10) Liste aller Tags ist in meinem Projektbericht, bzw. unter 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: Severin Forstinger

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

17 CSC (2/6) Beginnt mit /// Erste Zeile hat keine spezielle Bedeutung
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 Generierter Output wird in ein XML-Dokument gespeichert Severin Forstinger

18 CSC (3/6) /// text for class MyClass public class MyClass {
/// <param name="Int1">Used to indicate status.</param> public static void MyMethod(int Int1) { } /// text for Main public static void Main () { } } Severin Forstinger

19 CSC (4/6) <?xml version="1.0"?> <doc> <assembly>
<name>Project2</name> </assembly> <members> <member name="T:MyClass"> text for class MyClass </member> <member name="M:MyClass.MyMethod(System.Int32)"> <param name="Int1">Used to indicate status.</param> <member name="M:MyClass.Main"> text for Main </members> </doc> Severin Forstinger

20 CSC (5/6) Automatische Doc-Generierung Betrachtungsfähige Ausgabe:
Über Kommandozeile einstellbar (/doc:file) Über Compileroption (Build-Optionen) 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) Severin Forstinger

21 CSC (6/6) 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. <param> ob der angegebene Parameter tatsächlich existiert) Tags im Grunde nicht eingeschränkt, da alle gültigen XML-Tags erlaubt sind Severin Forstinger

22 Doxygen (1/5) 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) Severin Forstinger

23 Doxygen (2/5) Wurde unter Linux entwickelt
Portiert für: Unix, Windows, Solaris 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) Severin Forstinger

24 Doxygen (3/5) 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 Severin Forstinger

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

26 Doxygen (5/5) Hat eine Menge spezieller Tags (z.B. Gruppierung – in Javadoc über Cmd) 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! Severin Forstinger

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

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

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

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