Als ich mir zu Beginn meiner Arbeit einmal den Kopf über mein Thema zerbrochen habe und versuchte, mir ein Grobkonzept zurechtzulegen, konnte ich mir beim besten Willen nicht vorstellen, wie ich jemals 10 Seiten voll kriegen sollte.

Doch als ich anfing, mich näher mit den einzelnen Werkzeugen zu befassen, kam eine wahre Informationsflut auf mich eingestürzt. Vor allem da es sehr schwer war, sich zu entscheiden, was ich denn hier in meiner Arbeit vernachlässigen sollte. Wäre es doch schon allein möglich, über Javadoc mehr als 10 Seiten zu schreiben.

Und dabei hätte ich noch keine Beispiele berücksichtigt die oft für das Verständnis sehr hilfreich und wichtig sind.

So hoffe ich dennoch, einen brauchbaren Weg gefunden zu haben, um einem Einsteiger in die Thematik der Dokumentierwerkzeuge eine nützliche Hilfestellung vorlegen zu können.

2.) Motivation für die Verwendung solcher Werkzeuge

Für den folgenden Abschnitt, gehe ich davon aus, dass jeder Leser schon mehr oder weniger umfangreiche Programmierarbeiten hinter sich hat.

Wenn man nun in diesem Feld nicht nur für die Uni tätig war, sondern auch schon für Firmen tätig war, so wird man unweigerlich mit der Thematik der Dokumentation in Berührung gekommen sein. Und da die meisten Programmierer (so zumindest das meist gerechtfertigte Vorurteil) lieber mit Sourcecode herumspielen, als dazugehörige Dokumentationen zu schreiben, muss ein neuer Ansatz gefunden werden, um trotzdem brauchbare Projektunterlagen (Dokumentation, Buglist, ToDo-Listen, ...) zu bekommen.

Da gibt es zunächst personelle Aufgabenteilungen, z.B. besitzen große Firmen eigene Projektmitglieder, die nur für die Erstellung von solchen Dokumenten zuständig sind. Jedoch können auch die nicht ohne den Schöpfer des jeweiligen Codes exakte Unterlagen verfassen. Somit ist es wieder nötig, dass der Programmierer zumindest grundlegende Anmerkungen zu seinen Programmteilen zu machen.

Da es nun kaum machbar ist, neben dem Erstellen (oft sehr heikler) Codestücke in einem anderen Programm die nötigen Kommentare und Änderungen mitzuführen ohne den Faden zu verlieren, war der Schritt zur Überlegung, die Kommentare als Grundlage der Dokumentation zu verwenden nicht weit. Jedoch ist es mühsam und wohl kaum realisierbar, jemandem aufzutragen alle diese Kommentare zu extrahieren und daraus brauchbaren Text zu formen.

So ist es nicht weiter verwunderlich, dass sich alsbald Tools dafür gefunden haben, die diese Arbeit übernahmen und die Ergebnisse in weiterverarbeitbarer Form darstellten.

Das erste umfangreiche und effiziente Tool mit dem ich in meiner Programmiererlaufbahn in Berührung gekommen bin, war Javadoc. Seither haben anscheinend immer mehr Firmen, aber auch Einzelpersonen diese Idee aufgegriffen und ähnliche Tools entwickelt.

So ist es auch nicht weiter verwunderlich, dass man in Google mit den Stichwörtern "documentation", "tool" und "java" knapp 500,000 Einträge findet. Die gefunden Links verweisen auf die diversesten Tools, die alle möglichen Funktionalitäten zur Verfügung stellen.

Ich habe nun aus dieser Schwemme einige herausgegriffen und näher unter die Lupe genommen. Im folgenden Kapitel möchte ich drei davon näher vorstellen. Den Beginn wird Javadoc machen, da es sich in der Java-Welt durch seine umfassenden Fähigkeiten bereits manifestiert hat. Anschließen möchte ich mit dem Dokumentationsgenerator der in C# verfügbar ist (CSC /doc). Zum Abschluss werde ich noch ein fremdentwickeltes Tool namens Doxygen erläutern.

3.) Praktische Beipiele

3.1.) Javadoc

Wie der Name schon sagt, ist dieses Tool für die Dokumentationserstellung von Java-Programmen vorgesehen. Liest man sich die Geschichte von JavaDoc durch, so bekommt man den Eindruck, es wurde zu Beginn rein für firmeninterne Verwendung entworfen. Um aber die Open-Source-Eigenschaften von Java zu wahren und dabei ein konsistentes Layout der hinzugefügten API-Teile zu bekommen, wurde Javadoc der gesamten Entwicklergemeinde zur Verfügung gestellt.

Es wird von Sun darauf hingewiesen, dass Javadoc als Hauptziel die Erstellung von API Spezifikationen hat und keine Programmierrichtlinien generieren soll. Wobei ich der Meinung bin, dass eine sorgfältig dokumentierte API einem etwas kundigen Programmierer mehr bringt als ein Tutorial oder ähnliches.

Doc-Kommentare werden in Java mit /** begonnen. Abgeschlossen wird so ein Kommentar mit */. Dabei sollte der Anfangs- & Endbegrenzer (delimiter) jeweils auf einer eigenen Zeile stehen.

Ein Doc-Kommentar muss immer vor einer Klasse, einem Feld, einem Konstruktor oder einer Methode geschrieben werden und setzt sich aus 2 Teilen zusammen - der Beschreibung und der Liste von Tags.

Anmerkungen dazu:

· Seit Javadoc 1.4 sind die führenden * in jeder Zeile nicht mehr nötig.

· die erste Zeile wird als so genannte "short summary" bezeichnet. Javadoc übernimmt dies in den Index und die "summary-table".

· HTML-Tags können wie auf einer Webseite verwendet werden.

· Mit dem ersten Auftreten einer "@"-Zeile endet die Beschreibung, es gibt pro Doc-Kommentar nur eine Beschreibung, sie kann also nach den Tags nicht fortgesetzt werden!

das Ergebnis sieht wie folgt aus:

Erster Satz

Wie schon erwähnt, wird der erste Satz als Zusammenfassung angesehen und wird in den generierten Dateien als Kurzbeschreibung der jeweiligen Klasse/Interface, Package, usw... angegeben. Es ist daher wichtig, in diesem Satz eine kurze aber aussagekräftige Beschreibung zu verpacken. Als Ende des Satzes wird der "." angesehen. Dadurch kann folgende Situation enstehen:

/**

   * This is a simulation of Prof. Knuth's MIX computer.

*/

…würde bei "Prof." enden. Um das zu umgehen, hängt man hinter dem unerwünschten "." einen HTML-Metatag an, z.B.

/**

   * This is a simulation of Prof.&nbsp;Knuth's MIX computer.

*/

oder

/**

   * This is a simulation of Prof.<!-- --> Knuth's MIX computer.

*/

"Vererbung" von Kommentaren

Man kann sich u.U. eine Menge Tipparbeit ersparen, wenn man sich bewusst ist, dass Javadoc in speziellen Fällen Kommentare übernimmt. Dies geschieht wenn:

· eine Methode in einer Klasse eine Methode der Superklasse überschreibt (erzeugt einen Abschnitt "Overrides")

· eine Methode in einem Interface eine Methode in einem Superinterface überschreibt (erzeugt einen Abschnitt "Overrides")

· wenn eine Methode einer Klasse eine Methode eines Interfaces implementiert (erzeugt einen Abschnitt "Specified by")

3.2.) CSC

Ist ein in C# integriertes Tool, das XML-Dateien mit den extrahierten Kommentaren und deren Kategorie erzeugt. Da XML in C# die Grundlage aller Kommentare und Tags bildet, kann jeder beliebige korrekte XML-Tag verwendet werden, wobei aber nur wenige vom Compiler überprüft werden (siehe dazu die Tabelle mit den verfügbaren Tags weiter unten).Dazu ein Beispiel:


	$Textfeld: // xml_permission_tag.cs using System; class TestClass { /// <permission cref="Test">Everyone can access this method.</permission> private static void Test() { } public static void Main() { } }$

ergibt folgendes XML-Output:

Das Problem dabei ist, dass die weitere Verwendung dieses XML-Files dem Benutzer überlassen wird. C# erzeugt standardmäßig nicht mehr als diesen XML-Code.

Der Befehl "Build Comment Web Page"

Über das Programmmenü von C# findet man unter "Tools" den Befehl "Build Comment Web Page". Dieser Befehl lässt dem Benutzer wahlweise für ein Projekt oder die gesamte Solution HTM-Dateien aus den generierten XML-Dateien bilden, die man dann auch anschauen kann.

Vom Aufbau ähnelt das Ganze stark Javadoc, jedoch werden manche Informationen aus der XML-Datei (komischerweise!?) nicht angezeigt. Man nehme das Beispiel von oben und sieht, dass die permission eigentlich näher beschrieben ist, das HTM-File zeigt aber nur das an:

Wie schreibt man jetzt C# Doc-Kommentare?

Ähnlich wie schon manche Tools es in C(++) gemacht haben, beginnen Doc-Kommentare in C# mit ///, leider sind solche Kommentare nur einzeilig und man hat daher die /// in jeder Zeile neu zu schreiben. Das unten angeführte Codesegment stammt aus der C# Hilfe und kann gesamt unter

ms-help://MS.VSCC/MS.MSDNVS/csref/html/vcwlkXMLDocumentationTutorial.htm

gefunden werden.

using System;

/// <summary>

/// Class level summary documentation goes here.</summary>

/// <remarks>

/// Longer comments can be associated with a type or member

/// through the remarks tag</remarks>

public class SomeClass

  /// <summary>

  /// Store for the name property</summary>

  private string myName = null;

  /// <summary>

  /// The class constructor. </summary>

  public SomeClass()

........ usw.

Will man nun automatisch beim Kompilieren sich die entsprechenden XML-Dateien generieren lassen, so muss man dies dem Compiler unter den Project-Properties mitteilen. Dort stellt man unter der Build-Eigenschaft die entsprechende Ausgabedatei ein. Somit werden die Kommentare bei jedem Kompilieren in XML-Dateien extrahiert.

Sollte jemand das Ganze über Kommandozeile betreiben, so muss er den Parameter /doc:file angeben (wobei file wieder die XML-Ausgabedatei ist).

Verfügbare Tags

Der C# Compiler erkennt untenstehende Tags und überprüft bei den mit 1) markierten die Syntax.

XML-Tag	Bedeutung
<c>	stellt den Text dazwischen als Code dar
<code>	wie <c>
<example>	gibt den Text dazwischen als Beispiel wieder
<exception>¹	welche Exceptions können auftreten
<include>¹	bindet ein anderes XML-File ein
<list>	erzeugt eine Liste (bulleted, etc…)
<para>	alles dazwischen ist ein Absatz
<param>¹	beschreibt den vorhandenen Parameter
<paramref>¹	formatiert den entprechenden Namen als Parameter
<permission>¹	gibt die Zugriffsberechtigung an
<remarks>	spezielle Anmerkungen
<returns>	Rückgabewert einer Methode
<see>¹	Verweis auf einen anderen Feld oder Member
<seealso>¹	wie <see> nur in der "see also" Sektion untergebracht
<summary>	Zusammenfassung
<value>	beschreibt eine Property

3.3.) Doxygen

Doxygen wurde unter Linux entwickelt, steht aber für verschiedenste Plattformen zur Verfügung (Unix, Windows, Solaris). Es unterstützt des weiteren eine ganze Menge Ausgabeformate, dazu zählen:

· HTML

· XML

· RTF

· Unix-Man-Pages

· LaTeX

· Postscript

· PDF

außerdem kann man für C++ Dateien Vererbungsdiagramme erzeugen.

Weiters ist anzumerken, dass es nicht nur C und C++, sondern auch Java, C#, IDL und Pearl als Input akzeptiert.

Alles in allem kann man schon hier erkennen, dass Doxygen sehr mächtig ist. Die Kehrseite ist bloß, dass es auch ebenso umfangreich ist. Das Manual umfasst knapp 120 Seiten und man hat ca. geschätzte 70-100 Optionen die man für seine Dokumentation einstellen kann (was wird generiert, wie wird es formatiert, welchen Typ, etc...). Am besten kann man das wohl an einem Screenshot der Windowsversion erkennen:

Man kann aus diesem Screenshot nicht nur erahnen wie umfangreich das Programm und seine Einstellungen sind, sondern erkennt auch, dass es eindeutig von keinem Windows-Benutzer entwickelt wurde ;-).

Doc-Kommentare markieren

Doxygen kennt vier Arten von Doc-Kommentar-Begrenzern:

1. wie in Java /** .... */

2. wie in C(#/++) /// (in jeder Zeile)

3. Qt-Format Java /*! ..... */

4. Qt-Format C(#/++) //! (in jeder Zeile)

Eine Kleinigkeit ist auffällig - benutzt man Doxygen um Java-Files zu dokumentieren, so wird man manchen @param Eintrag vermissen. Das rührt daher, dass Doxygen den @param Tag vor jedem Parametereintrag verlangt, während Javadoc dies nur vor dem ersten will.

Javadoc

Doxygen

/**

* A test discription.

* @param var1 a simple varibale

* var2 another one

* @see…..

/**

* A test discription.

* @param var1 a simple varibale

* @param var2 another one

* @see…..

Spezielle Kommandos

Doxygen verwendet eine ganze Reihe spezieller Parameter, die den Parser zu bestimmten Aktionen veranlassen. Ich führe hier nur eine kleine List auf, da die Anzahl der Kommandos auch wieder sehr umfangreich ist:

· \structto document a C-struct.

· \fn to document a function.

· \var to document a variable or typedef or enum value.

· \def to document a #define.

· \namespaceto document a namespace.

· \packageto document a Java package.

· \interfaceto document an IDL interface.

Ein umfangreiches Beispiel kann man sich unter http://www.stack.nl/~dimitri/doxygen/docblocks.html anschauen (der Code ist ca. 1,5 Seiten lang, darum möchte ich ihn hier nicht einfügen).

Besonderheiten

Ähnlich wie in CSC kann man auch in Doxygen Listen und ähnliche Strukturen in den Kommentaren anlegen, um in der generierten Dokumentation einen besseren Überblick zu haben.

Die Gruppierung von Methoden, Klassen, etc. wird hier wiederum über spezielle Tags angegeben (im Vergleich dazu: Javadoc muss das über die Kommandozeile mitgeteilt werden).

Ein nettes Feature sei noch erwähnt. Man kann über den /f Tag LaTeX Formeln in die Kommentare schreiben, die dann in der Latex-Generierung auch in entsprechende Formeln umgewandelt werden.

The distance between \f$(x_1,y_1)\f$ and \f$(x_2,y_2)\f$ is

 \f$\sqrt{(x_2-x_1)^2+(y_2-y_1)^2}\f$.

results in:

The distance between and is .

Dazu muss allerdings LaTeX auf dem Rechner installiert sein!

4.) Vergleich und Bemerkungen

Wie man sieht, können die vorgestellten Programme schon eine ganze Menge.

4.1.) Javadoc

wirkt logischerweise schon sehr durchdacht und ausgeklügelt, ist es doch schon lange im Praxiseinsatz. Außerdem steht eine entsprechend erfahrene Entwicklermannschaft dahinter. Es ist daher aus meiner Sicht im Java-Sektor nicht viel zu überlegen. Wenn man nicht unbedingt extrem ausgefallene Vorstellungen und Wünsche hat, so kann Javadoc wohl alles nötige (vor allem die Definition von custom-Tags ist hier sehr vorteilhaft).

Unangenehm ist lediglich der schwierige Aufruf über die Kommandozeile, wie ein "kleines" Beispiel leicht beweisen kann:

This command line example is over 900 characters, which is too long for some shells, such as DOS. You can use a command line argument file (or write a shell script) to workaround this limitation.

% javadoc -sourcepath /java/jdk/src/share/classes            \

   -overview /java/jdk/src/share/classes/overview.html      \

   -d /java/jdk/build/api                                   \

   -use                                                     \

   -splitIndex                                              \

   -windowtitle 'Java 2 Platform v1.2 API Specification'    \

   -doctitle 'Java<sup><font size="-2">TM</font></sup> 2 Platform v1.2 API Specification' \

   -header '<b>Java 2 Platform </b><br><font size="-1">v1.2</font>' \

   -bottom '<font size="-1"><a href="http://java.sun.com/cgi-bin/bugreport.cgi">Submit

a bug or feature</a><br><br>Java is a trademark or registered trademark of Sun Microsystems,

Inc. in the US and other countries.<br>Copyright 1993-1999 Sun Microsystems, Inc.

901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A. All Rights Reserved.</font>' \

   -group "Core Packages" "java.*:com.sun.java.*:org.omg.*" \

   -group "Extension Packages" "javax.*"                    \

    -J-Xmx180m                                               \

    @packages

Hat man das jedoch mal unter Kontrolle, so ist Javadoc leicht einzusetzen.

4.2.) CSC

steckt wohl noch in den Kinderschuhen, zumindest hat es auf mich so gewirkt. Oder es soll mal wieder ein Zusatztool (ein guter XML-Parser für die generierten Dateien) verkauft werden. Aber die Ansätze sind gut und XML als Grundlage macht das Ganze wesentlich flexibler als Javadoc.

Die Einbindung in den Compiler ist durchaus ein logischer Schritt und auch sehr zu begrüßen, denn dadurch fällt ein zusätzlicher Arbeitsschritt weg, der wenn er z.B. vergessen wird auch durchaus Verwirrung stiften kann (Code und Dokumentation passen nicht zusammen).

Was im Vergleich noch unangenehm auffällt ist die Notwendigkeit vor jeder Zeile das /// zu wiederholen, was jedoch eher dem C-Compiler angelastet werden muss (keine mehrzeiligen Kommentare) als dem Dokumentierwerkzeug.

Meiner Meinung nach ein brauchbarer Ansatz, aber noch keine ausgereifte Lösung.

4.3.) Doxygen

Obwohl nur von einem einzelnen Programmierer entwickelt, ist es doch schon in Version 1.3 durchaus brauchbar und großteils fehlerfrei. Hauptsächlich deshalb entwickelt, weil anderen Tools spezielle Fähigkeiten gefehlt haben, was wieder einmal eine typische Programmierereigenschaft aufzeigt und gleichzeitig erklärt, warum soviele solcher Tools verfügbar sind.

"What was the reason to develop doxygen?

I once wrote a GUI widget based on the Qt library (it is still available at http://qdbttabular.sourceforge.net/and maintained by Sven Meyer). Qt had nicely generated documentation (using an internal tool which they didn't want to release) and I wrote similar docs by hand. This was a nightmare to maintain, so I wanted a similar tool. I looked at Doc++ but that just wasn't good enough (it didn't support signals and slots and did not have the Qt look and feel I had grown to like), so I started to write my own tool... "

Der große Vorteil ist, dass nicht nur eine Programmiersprache und ein Ausgabeformat unterstützt wird, sondern gleich ein paar gängige. Wodurch sich auch der enorme Aufwand es zu erlernen rechtfertigen lässt. Und das ist auch schon der große Nachteil an Doxygen. Will man nur selten oder wenig umfangreiche bzw. komplizierte Dokumentationen generieren, so steht der Aufwand des Erlernens kaum dafür, und man wird mit den (meist schon mitgelieferten) Dokumentationstools das Auslangen finden.

5.) Abschließende Kommentare

Nun kann man nach dieser kleinen Einführung erkennen, dass dem Programmierer schon viel von der früheren Last des Dokumentierens abgenommen wird und er sich mehr auf guten Quellcode konzentrieren kann. Doch kein Tool ist in der Lage, ihn von seiner Aufgabe zu befreien, seine Programme und -teile zu kommentieren und zu dokumentieren. Nicht nur im Sinne seiner Kollegen und Kunden, sondern auch in seinem eigenen. Denn wer kennt das nicht, nach einem halben Jahr wieder mal ein eigenes Programm zu lesen und nicht mehr genau zu wissen, was es macht, oder wie es aufgebaut ist.

Ist es allerdings in entsprechender Weise kommentiert, so kann mit Hilfe eines solchen Dokumentierwerkzeugs bald wieder Licht in das Dunkel gebracht werden.

Abschließend möchte ich noch anmerken, dass meiner Meinung nach, die Dokumentierwerkzeuge eher für die Hilfe der Programmierer ein Programm leichter zu verstehen gemacht worden sind, als um fertige Benutzerhandbücher damit erstellen zu können. Das ist eine Illusion der man sich nicht hingeben sollte.

6.) Weiterführende Informationen

Wie schon erwähnt, gibt es unzählige solcher Tools und ich habe nur einen winzigen Ausschnitt behandelt. Daher führe ich hier ein paar Links für Interessierte an, die einen guten Einstieg in dieses Thema darstellen:

http://www.python.org/sigs/doc-sig/otherlangs.html	mehrere Links zu div. Seiten
http://docpp.sourceforge.net/manual/index.html	Doc++ Homepage
http://www.python.org/	Python
http://www.stack.nl/~dimitri/doxygen/index.html	Doxygen Homepage & Quickstart
http://www.swbs.com/	CDOC, kleines Tool
http://java.sun.com/j2se/javadoc/	Javadoc Homepage

A.) Appendix

A.1.) Literatur- und Linkliste

· Simon Robinson et al.: Professional C#. Wrox, 2001

· Gerhard Wilms: C++ Das Grundlagenbuch, Data Becker, 2001

· http://java.sun.com/j2se/1.4/docs/tooldocs/solaris/javadoc.html

· http://java.sun.com/j2se/javadoc/writingdoccomments/index.html

· http://www.stack.nl/~dimitri/doxygen/index.html

· Microsoft VisualStudio .NET Hilfe

· http://msdn.microsoft.com/library/default.asp (.NET Bereich)

Tag	seit
`@author`	1.0	Verfasser des Programms (können auch mehrere sein)
`{@docRoot}`	1.3	stellt den relativen Pfad zum Doc-Verzeichnis dar
`@deprecated`	1.0	veraltet, sollt mit {@link } auf einen Ersatz verweisen
`@exception`	1.0	welche Exceptions werden geworfen
`{@inheritDoc}`	1.4	kopiert den doc-Text aus der Superclass
`{@link}`	1.2	Verweis auf anderes Dokument
`{@linkplain}`	1.4	wie {@link}, verlinkt aber über den Text, nicht das Codewort
`@param`	1.0	Paramaterbeschreibung
`@return`	1.0	Rückgabewert und ev. Beschreibung
`@see`	1.0	ähnlich wie {@link}, nur Standalone
`@serial`	1.2	zeigt serializable an
`@serialData`	1.2	zeigt serializable von Daten an
`@serialField`	1.2	zeigt serializable von Feldern an
`@since`	1.1	seit wann etwas vorhanden ist
`@throws`	1.2	synonym zu @exception
`{@value}`	1.4	zeigt Konstantenwerte an
`@version`	1.0	zeigt die Version an (spezieller Text %I%,%G%)