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

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

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 10.01.03 Severin Forstinger

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 10.01.03 Severin Forstinger

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 10.01.03 Severin Forstinger

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) 10.01.03 Severin Forstinger

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 erstes @) Tag-list (Liste aller Standalone-Tags) 10.01.03 Severin Forstinger

Javadoc (3/10) Tags Standalone: können nur in der Tag-list verwendet werden Notation: @tag Inline: können überall im Doc-Kommentar eingesetzt werden Notation: {@tag} Custom: können über die Kommandozeile spezifiziert werden 10.01.03 Severin Forstinger

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

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

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. 10.01.03 Severin Forstinger

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 10.01.03 Severin Forstinger

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

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 10.01.03 Severin Forstinger

Javadoc (10/10) Liste aller Tags ist in meinem Projektbericht, bzw. unter http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/javadoc.html#javadoctags 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: http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/javadoc.html#realworldexample 10.01.03 Severin Forstinger

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 10.01.03 Severin Forstinger

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 10.01.03 Severin Forstinger

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 () { } } 10.01.03 Severin Forstinger

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> 10.01.03 Severin Forstinger

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) 10.01.03 Severin Forstinger

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 10.01.03 Severin Forstinger

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) 10.01.03 Severin Forstinger

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

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 ein @param-Tag stehen 10.01.03 Severin Forstinger

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

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! 10.01.03 Severin Forstinger

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 10.01.03 Severin Forstinger

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 10.01.03 Severin Forstinger

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 10.01.03 Severin Forstinger

Weiterführende Infos Einen guten Einstieg in die Thematik findet man unter folgenden Links: http://www.python.org/sigs/doc-sig/otherlangs.html http://docpp.sourceforge.net/manual/index.html http://www.python.org/ http://www.stack.nl/~dimitri/doxygen/index.html http://www.swbs.com/ http://java.sun.com/j2se/javadoc/ 10.01.03 Severin Forstinger