Dokumentierwerkzeuge

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
2
Einleitung

Tools schon länger bekannt
– Firmenintern
– Speziallösungen (Preis!)
– Selbst „gestrickt“
Keine Normen vorhanden

Wurde bald als wichtig erkannt
10.01.03
Severin Forstinger
3
Motivation

Firmenseitig
– Neue Module haben konsistentes APILayout (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
4
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
5
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
6
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
7
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
8
Javadoc (4/10)
/**
* @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 InlineTag
10.01.03
Severin Forstinger
9
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
10
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
11
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 TagListe soll eine Leerzeile eingefügt werden
10.01.03
Severin Forstinger
12
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
13
Javadoc (9/10)

Package-level Kommentare
– Werden in einer Datei package.html
geschrieben (inline-tags können verwendet
werden)
– Diese Datei wird in das PackageVerzeichnis kopiert (zu den .java-Dateien)
– Javadoc sucht nach dieser Datei und
kopiert den Inhalt in den PackageDescription Abschnitt
– Erste Zeile kommt in die OverviewSummary
10.01.03
Severin Forstinger
14
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
15
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
16
CSC (2/6)

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
 Generierter Output wird in ein XMLDokument gespeichert

10.01.03
Severin Forstinger
17
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
18
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>
<member name="M:MyClass.Main">
text for Main
</member>
</members>
</doc>
10.01.03
Severin Forstinger
19
CSC (5/6)

Automatische Doc-Generierung
– Ü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
20
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
21
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
22
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
23
Doxygen (3/5)

Mehrere Arten von
Kommentarbezeichnern
– Java
– C(#/++)
– Qt-Format Java
– Qt-Format C(#/++)

/** ... */
/// (in jeder Zeile)
/*! ... */
//! (in jeder Zeile)
Anders als in Javadoc muss vor jedem
Parameter ein @param-Tag stehen
10.01.03
Severin Forstinger
24
Doxygen (4/5)
Javadoc
/**
* A test discription.
* @param var1 a simple varibale
*
var2 another one
* @see…..
*/
Doxygen
/**
* A test discription.
* @param var1 a simple varibale
* @param var2 another one
* @see…..
*/
Tags entweder im Java-Stil (@tag)
 Doxygen eigenes Format \tag

10.01.03
Severin Forstinger
25
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 DoxygenHomepage) können auch umfangreicherer
Diagramme erstellt werden

Sehr komplex – Manual hat 120 Seiten!
10.01.03
Severin Forstinger
26
Zusammenfassung (1/2)

Javadoc
+ 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
27
Zusammenfassung (2/2)

Doxygen
+ 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
28
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
29
Weiterführende Infos

Einen guten Einstieg in die Thematik findet
man unter folgenden Links:
–
–
–
–
–
–
10.01.03
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/
Severin Forstinger
30