dokumentierwerkzeuge eine seminararbeit im rahmen der lva programmierstil erstellt von severin...

DokumentierwerkzeugeDokumentierwerkzeuge

Eine Seminararbeit im Rahmen der Eine Seminararbeit im Rahmen der LVA LVA „Programmierstil“„Programmierstil“

erstellt vonerstellt von

Severin ForstingerSeverin Forstinger

10.01.03 Severin Forstinger 2

Gliederung des VortragsGliederung des Vortrags

Einleitung & MotivationEinleitung & Motivation Praktische BeispielePraktische Beispiele

– JavaDocJavaDoc– CSC (C#-Tool) CSC (C#-Tool) – DoxygenDoxygen– Weiterführende LinksWeiterführende Links

ZusammenfassungZusammenfassung AnmerkungenAnmerkungen Weiterführende InformationenWeiterführende Informationen


EinleitungEinleitung

Tools schon länger bekanntTools schon länger bekannt– FirmeninternFirmenintern– Speziallösungen (Preis!)Speziallösungen (Preis!)– Selbst „gestrickt“Selbst „gestrickt“

Keine Normen vorhandenKeine Normen vorhanden

Wurde bald als wichtig erkanntWurde bald als wichtig erkannt


MotivationMotivation

FirmenseitigFirmenseitig– Neue Module haben konsistentes API-Neue Module haben konsistentes API-

Layout (vgl. Java)Layout (vgl. Java)– Anreiz zum Einsatz des ProduktsAnreiz zum Einsatz des Produkts

ProgrammiererseitigProgrammiererseitig– Muss nicht zwischen Programmier- & Muss nicht zwischen Programmier- &

Dokumentationswerkzeug wechselnDokumentationswerkzeug wechseln– „„Dokumentation“ geht neben Codeentwurf Dokumentation“ geht neben Codeentwurf

» verliert nicht den Fadenverliert nicht den Faden» vergisst kaum, etwas zu beschreibenvergisst kaum, etwas zu beschreiben


Praktische BeispielePraktische Beispiele

Aus der Fülle an Tools drei ausgewähltAus der Fülle an Tools drei ausgewählt– Javadoc (da sehr bekannt und erprobt)Javadoc (da sehr bekannt und erprobt)– CSC (C#, da eine Neuerung)CSC (C#, da eine Neuerung)– Doxygen (als Vertreter von Doxygen (als Vertreter von

produktfremden Werkzeugen)produktfremden Werkzeugen)

Alleine Javadoc im Detail würde einen Alleine Javadoc im Detail würde einen Vortrag füllenVortrag füllen


Javadoc (1/10)Javadoc (1/10)

Anfangs bei Sun intern verwendetAnfangs bei Sun intern verwendet Bald als Tool im JDK enthaltenBald als Tool im JDK enthalten Erzeugt HTML-DateienErzeugt HTML-Dateien Möglich für:Möglich für:

– Source Code .java (class, interface, field, Source Code .java (class, interface, field, constructor, method comments)constructor, method comments)

– Package comment files (package.html)Package comment files (package.html)– Overview comment filesOverview comment files– Div. Files (als Refernenzziel)Div. Files (als Refernenzziel)



Beginnt mit /** und endet mit */Beginnt mit /** und endet mit */ Dazwischen HTML (jeder HTML-Tag ist Dazwischen HTML (jeder HTML-Tag ist

gültig) mit speziellen Javadoc-Tagsgültig) mit speziellen Javadoc-Tags Muss vor einer Muss vor einer class, field, constructor class, field, constructor

oodeder method declaration r method declaration stehenstehen 2 Teile:2 Teile:

– Description (Beschreibung bis erstes @)Description (Beschreibung bis erstes @)– Tag-list (Liste aller Standalone-Tags)Tag-list (Liste aller Standalone-Tags)



TagsTags– Standalone: können nur in der Tag-list Standalone: können nur in der Tag-list

verwendet werdenverwendet werdenNotation: @tagNotation: @tag

– Inline: können überall im Doc-Kommentar Inline: können überall im Doc-Kommentar eingesetzt werdeneingesetzt werdenNotation: {@tag}Notation: {@tag}

– Custom: können über die Kommandozeile Custom: können über die Kommandozeile spezifiziert werdenspezifiziert werden



/** /**

* @deprecated As of JDK 1.1, replaced * @deprecated As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)} by {@link #setBounds(int,int,int,int)}

*/ */

Dabei ist Dabei ist – @deprecated @deprecated ein Standalone-Tagein Standalone-Tag– {@link #setBounds(int,int,int,int)}{@link #setBounds(int,int,int,int)} ein ein

Inline-TagInline-Tag



/**/**

* 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.

**

* @param str ein String, der ausgegeben werden * @param str ein String, der ausgegeben werden sollsoll

*/*/

public void writeText(String str) {public void writeText(String str) {

System.out.println(str);System.out.println(str);

}}

Erste Zeile wird als Zusammenfassung Erste Zeile wird als Zusammenfassung interpretiertinterpretiert– Wird in den Index kopiertWird in den Index kopiert– Wird in der summary-table eingetragenWird in der summary-table eingetragen

Erste Zeile endet mit dem ersten „.“Erste Zeile endet mit dem ersten „.“– Problem: * this is Prof. Knuth‘s mix.Problem: * this is Prof. Knuth‘s mix.– Lösung: HTML Tag dahinter einfügenLösung: HTML Tag dahinter einfügen

* this is Prof. Knuth‘s mix.* this is Prof. Knuth‘s mix.oderoder * this is Prof. Knuth‘s mix.* this is Prof. Knuth‘s mix.



Die erzeugte Ausgabe schaut so aus: Die erzeugte Ausgabe schaut so aus: Java-AusgabeJava-Ausgabe

AnmerkungenAnmerkungen– Seit Javadoc 1.4 ist das * am Beginn jeder Seit Javadoc 1.4 ist das * am Beginn jeder

Zeile nicht mehr nötig.Zeile nicht mehr nötig.– /** und */ sollten in einer eigenen Zeile /** und */ sollten in einer eigenen Zeile

stehenstehen– Zwischen der Beschreibung und der Tag-Zwischen der Beschreibung und der Tag-

Liste soll eine Leerzeile eingefügt werdenListe soll eine Leerzeile eingefügt werden



BesonderheitenBesonderheiten– Es gibt pro Doc-Kommentar nur eine Es gibt pro Doc-Kommentar nur eine

Beschreibung die beim ersten @ endet.Beschreibung die beim ersten @ endet.Sie kann danach nicht mehr fortgesetzt Sie kann danach nicht mehr fortgesetzt werden.werden.

– Parameter werden nicht automatisch Parameter werden nicht automatisch dokumentiert, es ist für jeden ein @param dokumentiert, es ist für jeden ein @param nötig.nötig.

– Mit einem Return-Wert ist es ebenso, Mit einem Return-Wert ist es ebenso, dieser wird mit @return festgelegt.dieser wird mit @return festgelegt.



Package-level KommentarePackage-level Kommentare– Werden in einer Datei package.html Werden in einer Datei package.html

geschrieben (inline-tags können verwendet geschrieben (inline-tags können verwendet werden)werden)

– Diese Datei wird in das Package-Diese Datei wird in das Package-Verzeichnis kopiert (zu den .java-Dateien)Verzeichnis kopiert (zu den .java-Dateien)

– Javadoc sucht nach dieser Datei und Javadoc sucht nach dieser Datei und kopiert den Inhalt in den Package-kopiert den Inhalt in den Package-Description AbschnittDescription Abschnitt

– Erste Zeile kommt in die Overview-Erste Zeile kommt in die Overview-SummarySummary



Liste aller Tags ist in meinem Liste aller Tags ist in meinem Projektbericht, bzw. unter Projektbericht, bzw. unter http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/javadoc.html#javadoctagshttp://java.sun.com/j2se/1.4/docs/tooldocs/solaris/javadoc.html#javadoctags

Aufruf über javadoc.exe (in jdk\bin)Aufruf über javadoc.exe (in jdk\bin)– Hat eine Fülle von Parametern (56 Stück)Hat eine Fülle von Parametern (56 Stück)– Oft muss über ein Makefile gearbeitet Oft muss über ein Makefile gearbeitet

werden, da sonst die Eingabe zu lang wird werden, da sonst die Eingabe zu lang wird (z.B. DOS)(z.B. DOS)

Ein „lustiges“ Beispiel sowie alle Parameter Ein „lustiges“ Beispiel sowie alle Parameter findet man hier:findet man hier:

http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/javadoc.html#realworldexamplehttp://java.sun.com/j2se/1.4/docs/tooldocs/solaris/javadoc.html#realworldexample


CSC (1/6)CSC (1/6)

Im C# Compiler integriert, daher nur für Im C# Compiler integriert, daher nur für C# verwendbarC# verwendbar

Bildet XML-Dateien (Kategorie+Daten)Bildet XML-Dateien (Kategorie+Daten) Alle XML-Tags gültig, aber nur wenige Alle XML-Tags gültig, aber nur wenige

haben spezielle Bedeutunghaben spezielle Bedeutung Erzeugt keine formatierte Ausgabe wie Erzeugt keine formatierte Ausgabe wie

JavadocJavadoc


CSC (2/6)CSC (2/6)

Beginnt mit ///Beginnt mit ///– Dieser Kommentar ist nur einzeilig, daher Dieser Kommentar ist nur einzeilig, daher

muss /// vor jeder Zeile wiederholt werden.muss /// vor jeder Zeile wiederholt werden.– Muss vor dem zugehörigen Objekt stehen.Muss vor dem zugehörigen Objekt stehen.– Jeder gültige XML-Tag wird verarbeitet.Jeder gültige XML-Tag wird verarbeitet.

Erste Zeile hat keine spezielle Erste Zeile hat keine spezielle BedeutungBedeutung

Generierter Output wird in Generierter Output wird in einein XML- XML-Dokument gespeichertDokument gespeichert


CSC (3/6)CSC (3/6)

/// text for class MyClass /// text for class MyClass

public class MyClass { public class MyClass {

/// <param name="Int1">Used to indicate /// <param name="Int1">Used to indicate status.</param> public static void status.</param> public static void MyMethod(int Int1) { } MyMethod(int Int1) { }

/// text for Main /// text for Main

public static void Main () { } public static void Main () { }

} }


CSC (4/6)CSC (4/6)

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


CSC (5/6)CSC (5/6)

Automatische Doc-Generierung Automatische Doc-Generierung – Über Kommandozeile einstellbar (/doc:file)Über Kommandozeile einstellbar (/doc:file)– Über Compileroption (Build-Optionen)Über Compileroption (Build-Optionen)

Betrachtungsfähige Ausgabe:Betrachtungsfähige Ausgabe:– Über Befehl im Programm möglichÜber Befehl im Programm möglich– Unter „Tools“, „Build Comment Web Page“Unter „Tools“, „Build Comment Web Page“– Erzeugt mehrere HTM-Dateien, die die Erzeugt mehrere HTM-Dateien, die die

Struktur des Projekts bzw. der Solution Struktur des Projekts bzw. der Solution generiert (ähnlich dem Aussehen von generiert (ähnlich dem Aussehen von Javadoc)Javadoc)


CSC (6/6)CSC (6/6)

Liste aller besonderen XML-Tags findet Liste aller besonderen XML-Tags findet man in der VS .NET Hilfe, bzw. in man in der VS .NET Hilfe, bzw. in meinem Projektberichtmeinem Projektbericht– Es gibt 18 StückEs gibt 18 Stück– Manche werden vom Compiler überprüft Manche werden vom Compiler überprüft

(z.B. <param> ob der angegebene (z.B. <param> ob der angegebene Parameter tatsächlich existiert)Parameter tatsächlich existiert)

Tags im Grunde nicht eingeschränkt, da Tags im Grunde nicht eingeschränkt, da alle gültigen XML-Tags erlaubt sindalle gültigen XML-Tags erlaubt sind


Doxygen (1/5)Doxygen (1/5)

Ist von einem Programmierer entwickelt Ist von einem Programmierer entwickelt worden, weil er spezielle Fähigkeiten worden, weil er spezielle Fähigkeiten des Tools benötigtedes Tools benötigte– Unterstützt C, C++, C#, Java, PHP, IDLUnterstützt C, C++, C#, Java, PHP, IDL– Mögliche Ausgabeformate sind HTML, Mögliche Ausgabeformate sind HTML,

XML, RTF, Latex, PDF, PS, Unix-ManpageXML, RTF, Latex, PDF, PS, Unix-Manpage– Für C++ kann man Vererbungsdiagramme Für C++ kann man Vererbungsdiagramme

generieren (bei Mehrfachvererbung sehr generieren (bei Mehrfachvererbung sehr nützlich)nützlich)



Wurde unter Linux entwickeltWurde unter Linux entwickelt Portiert für: Unix, Windows, SolarisPortiert für: Unix, Windows, Solaris

Doxygen ist sehr mächtig, aber dadurch Doxygen ist sehr mächtig, aber dadurch auch sehr kompliziertauch sehr kompliziert– Knapp 70-100 Optionen die man bei der Knapp 70-100 Optionen die man bei der

Generierung angeben kannGenerierung angeben kann– Sehr unübersichtliche Oberfläche (siehe Sehr unübersichtliche Oberfläche (siehe

Screenshot im Projektbericht)Screenshot im Projektbericht)



Mehrere Arten von Mehrere Arten von KommentarbezeichnernKommentarbezeichnern– Java Java /** ... *//** ... */– C(#/++)C(#/++) //////

(in jeder Zeile)(in jeder Zeile)– Qt-Format JavaQt-Format Java /*! ... *//*! ... */– Qt-Format C(#/++)Qt-Format C(#/++) //!//!

(in jeder Zeile)(in jeder Zeile) Anders als in Javadoc muss vor jedem Anders als in Javadoc muss vor jedem

Parameter ein @param-Tag stehenParameter ein @param-Tag stehen



Tags entweder im Java-Stil (@tag)Tags entweder im Java-Stil (@tag) Doxygen eigenes Format \tagDoxygen eigenes Format \tag

JavadocJavadoc DoxygenDoxygen/**/**

* A test discription.* A test discription.

* @param var1 a simple varibale* @param var1 a simple varibale

* var2 another one* var2 another one

* @see…..* @see…..

*/*/

/**/**

* A test discription.* A test discription.

* @param var1 a simple varibale* @param var1 a simple varibale

* * @param@param var2 another one var2 another one

* @see…..* @see…..

*/*/



Hat eine Menge spezieller Tags (z.B. Hat eine Menge spezieller Tags (z.B. Gruppierung – in Javadoc über Cmd)Gruppierung – in Javadoc über Cmd)

BesonderheitenBesonderheiten– Kann Latexformeln generieren (wenn Latex Kann Latexformeln generieren (wenn Latex

installiert ist)installiert ist)– Über ein Plugin (Link auf der Doxygen-Über ein Plugin (Link auf der Doxygen-

Homepage) können auch umfangreicherer Homepage) können auch umfangreicherer Diagramme erstellt werdenDiagramme erstellt werden

Sehr komplex – Manual hat 120 Seiten!Sehr komplex – Manual hat 120 Seiten!


Zusammenfassung (1/2)Zusammenfassung (1/2)

Javadoc Javadoc + Für Java bestens geeignetFür Java bestens geeignet+ Langer PraxiseinsatzLanger Praxiseinsatz- Umständlich auszuführenUmständlich auszuführen

CSCCSC+ Im Compiler integriertIm Compiler integriert+ Sehr flexibelSehr flexibel– Noch in den KinderschuhenNoch in den Kinderschuhen– Zusatztool notwendigZusatztool notwendig


Zusammenfassung (2/2)Zusammenfassung (2/2)

DoxygenDoxygen+ Für viele Produkte geeignetFür viele Produkte geeignet+ Viele ZusatzfunktionenViele Zusatzfunktionen± Sehr umfangreichSehr umfangreich– Umständlich sich einzuarbeitenUmständlich sich einzuarbeiten

AllgemeinAllgemein– Alles in allem schon sehr viel FunktionalitätAlles in allem schon sehr viel Funktionalität– Sehr nützlich und nötigSehr nützlich und nötig– Wird noch intensiver werdenWird noch intensiver werden


AnmerkungenAnmerkungen

Tools schon sehr brauchbarTools schon sehr brauchbar Eher eine Hilfe für den Programmierer Eher eine Hilfe für den Programmierer

selbstselbst Generierte Version hat wenig mit einer Generierte Version hat wenig mit einer

endgültigen Dokumentation zu tun, eher endgültigen Dokumentation zu tun, eher nur ein Grundgerüstnur ein Grundgerüst


Weiterführende InfosWeiterführende Infos

Einen guten Einstieg in die Thematik findet man Einen guten Einstieg in die Thematik findet man unter folgenden Links:unter folgenden Links:

– http://www.python.org/sigs/doc-sig/http://www.python.org/sigs/doc-sig/otherlangs.htmlotherlangs.html

– http://docpp.sourceforge.net/manual/index.htmlhttp://docpp.sourceforge.net/manual/index.html– http://www.python.org/http://www.python.org/– http://www.stack.nl/~dimitri/doxygen/http://www.stack.nl/~dimitri/doxygen/

index.htmlindex.html– http://www.swbs.com/http://www.swbs.com/– http://java.sun.com/j2se/javadoc/http://java.sun.com/j2se/javadoc/

dokumentierwerkzeuge eine seminararbeit im rahmen der lva programmierstil erstellt von severin...

Documents