Beschreibung

Wer sich schon einmal in ein umfangreiches Software-Projekt einarbeiten musste, sei es zur Fehlersuche oder zwecks Änderung/Erweiterung, kann ein Lied davon singen, was es heißt ohne gute Dokumentation den Überblick über das Projekt zu bekommen.
Entwickler neigen ja gerne dazu schnell mal eine Änderung am Quellcode auszuprobieren, die bei Erfolg allenfalls irgendwo zwischen den Codezeilen mit einem knappen Kommentar dokumentiert wird und ansonsten für den Rest der Welt unbekannt bleibt.
Doxygen ist ein bekanntes Open-Source-Dokumentationstool, welches an dieser Stelle ansetzt und Sourcecode automatisch dokumentieren kann.
Dazu werden im Sourcecode spezielle Kommentare zu Methoden, Klassen, Variablen oder anderen Programmteilen geschrieben, aus denen Doxygen eine recht übersichtliche Dokumentation erstellt.
Zudem kann Doxygen Zusammenhänge zwischen Klassen und deren Instanzen (Vererbungshierarchie) und Abhängigkeiten zwischen Methoden visuell darstellen, was insbesondere bei objektorientierten Projekten sehr nützlich ist.
Dieser Schnellkurs, ursprünglich für die Teilnehmer des C-Kurses der FH-Offenburg geschrieben, beschreibt die Installation, Konfiguration und Handhabung von Doxygen und dem Plugin Graphviz DOT für ein Windowssystem.
(Eine Anleitung zur Installation unter Linux findet sich beispielsweise hier: http://www.selflinux.org/selflinux/html/doxygen01.html)
Da dies, wie gesagt, ein Schnellkurs ist, werden hier tiefergehende Details, wie z.B. das Einbinden eigener Bilder, HTML-Syntax in Doxygenkommentaren, nur am Rande beschrieben - es wird jedoch anhand eines kleinen Beispielprojektes das für Doxygen nötige Kommentarformat ausführlich erklärt.

Dokumentieren und Kommentieren

Wer Software schreibt, kommt ab einem gewissem Umfang nicht umhin seinen Code zu kommentieren.
Das geschieht i.d.R. direkt im Sourcecode.
Beispiel:
Code:
/*Das ist ein Kommentar
über mehrere
Zeilen*/
for(i=0;i<10;i++)
{
  printf("Hello World\n"); //Das ist ein Kommentar bis zum Zeilenende
}
Wie wichtig das Kommentieren ist, merkt man spätestens, wenn man seinen Code eine Weile nicht bearbeitet hat und dann zu einem späteren Zeitpunkt weiter machen will, oder etwas ändern möchte. Wenn man sich dann erst einmal in seinen eigenen Code wieder einarbeiten muss, ist das nicht nur peinlich, sondern bedeutet auch einen Zeitverlust.
Und richtig fatal wird das Problem, wenn mehrere Personen an dem Projekt arbeiten und nicht genügend kommentiert wird...
Kommentiert werden muss also, ganz ohne Frage, ohnehin - die Kommentare dienen aber in erster Linie nur den Programmierern.
Neben dem Kommentieren des Quellcodes ist es aber oftmals auch nötig das Projekt zu dokumentieren.
Eine Dokumentation dient Präsentationszwecken, erleichtert es Außenstehenden sich in das Projekt einzuarbeiten und ist nach Abschluss des Projektes ein aushändigbares Ergebnis.
Und, wie bereits eingangs erwähnt, setzt an dieser Stelle Doxygen an und nimmt dem Entwickler die zusätzliche Dokumentierungsarbeit ab.
Bevor wir aber dazu kommen, wie Doxygen dies anstellt, wenden wir uns zunächst der Installation und Konfiguration zu...

Installation und Konfiguration

Zunächst müssen wir Doxygen hier downloaden (5.4 MB).
Und wo wir gerade schon einmal dabei sind, downloaden wir auch gleich noch Graphviz DOT
Graphviz DOT ist ein kleines PlugIn für Doxygen, das Abhängigkeiten und Programmpfade bildlich darstellen kann, aber dazu gleich mehr...
Wir installieren jetzt zuerst Doxygen und gleich danach Graphviz.
Graphviz benötigt keine Konfiguration, Doxygen hingegen schon.
Also rufen wir nun Doxygen auf:
Start → Programme → doxygen → doxywizard

Im Doxygen-Fenster wählen wir "Expert..." und hangeln uns zum Reiter "Dot" durch (vorletzter).
Hier müssen wir beim ersten Start von Doxygen nun mitteilen, dass Graphviz installiert ist und wo es sich befindet.
Also "HAVE_DOT" setzen und den Pfad zu den Graphviz-Binaries angeben.
Im Übrigen sollten wir alle diese Einstellungen setzen:
DOT-Einstellungen

Achtung!
Bei der Pfadangabe zu Dot nicht die Windows-typischen Backslashs '\' verwenden, sondern normale Slashes '/'.
Also z.B. 'C:/' statt 'C:\'

Man macht auch nichts falsch, wenn man hier kurzerhand einfach alles aktiviert...
So, jetzt mit Klick auf "OK" die Einstellungen übernehmen.

Zurück im Hauptfenster klicken wir nun "Wizard..." an und werden nach einem Projektnamen gefragt.
Hier also den Projektnamen angeben und als Version z.B. "Version 1.0".
Unter Source code directory ist der Ordner der Code-Dateien anzugeben.
Den gleichen Ordner sollte man praktischer Weise auch darunter bei Destination directory angeben - Doxygen erstellt dann in diesem Ordner ein "html"-Verzeichnis mit der Dokumentation.
Jetzt in den Reiter "Mode" wechseln und unter "Select programming language to optimize the results for" die Codesprache (C, C++ oder Java) angeben.
Im Reiter "Output" deaktiviert man die LaTeX-Option - es sei denn neben der HTML-Dokumentation wäre auch eine LaTeX-Doku erwünscht.
So, nun werfen wir noch einen Blick in den Reiter "Diagrams" und überprüfen, ob die Einstellungen diesen hier entsprechen:
DOT-Einstellungen

Nachdem alles mit "OK" bestätigt wurde, geht es nochmals in die Expert-Optionen und hier wählt man im Reiter "Project" unter OUTPUT_LANGUAGE German aus.

Das war's dann auch schon an nötigen Einstellungen.
Damit das Prozedere nicht jedes Mal wiederholt werden muss, speichert man die Einstellungen in einer Doxyfile.
Also im Hauptfenster auf "Save..." klicken und die Doxyfile im Projektordner abspeichern.

Eine Kleinigkeit will Doxygen jetzt noch: unter Working directory müssen wir einen Pfad angeben, von dem Doxygen aus startet.
Da standardmäßig der Installation von Doxygen der Pfad zu den Doxygen-Binaries zur PATH-Liste hinzugefügt wird, kann hier ein x-beliebiges Verzeichnis angegeben werden.
(Um festzustellen, ob der Binaries-Pfad in der PATH-Liste steht, reicht es ein Konsolenfenster zu öffnen (Start->Ausführen->"cmd") und mit "PATH" zu überprüfen, ob hier irgendwo "C:\Programme\doxygen\bin" steht.)

Geschafft!
Mit Klick auf "Start" generiert Doxygen nun die Dokumentation im Unterordner "html" des Projektverzeichnisses.
In diesem html-Ordner wiederum befindet sich alsdann auch eine "index.html".
Und das wollen wir uns jetzt genauer ansehen...

Zur Veranschaulichung steht hier ein exemplarisches Java-Projekt zu Download zur Verfügung:
Doxygen Beispielprojekt (190kB)
Und hier die mit Doxygen erstellte zugehörige HTML-Dokumentation zur direkten Ansicht im Browser:
Doxygen Beispielprojekt - Dokumentation

Kurz ein paar Worte zum Beispielprogramm:
Es handelt sich hierbei um ein Java-Programm, welches Integerarrays mit verschiedenen Sortieralgorithmen sortiert und den Sortierprozess grafisch anzeigt (Screenshot).
Es werden die Algorithmen Selectionsort, Insertionsort und Bubblesort verglichen.
Um das Programm auszuführen wird die Java Runtime Environment (JRE) von Sun Microsystems benötigt.

Die Doxygen-Kommentare

Funktion und Zweck des Beispielprogrammes sind an dieser Steller aber unbedeutend - nun geht es um die erstellte Dokumentation.
Wie eingangs bereits erwähnt, benutzt Doxygen ein spezielles Kommentarformat - und wer sich den Quellcode des Beispielprogrammes ansieht, wird hier auf mehrzeilige Kommentare stoßen, die mit einem /** ("Slash-Doppelsternchen") eingeleitet werden.
Dies ist die typische Syntax der Doxygenkommentare. Das zweite Sternchen dient Doxygen dabei zur Unterscheidung von nicht zu dokumentierenden, mehrzeiligen Kommentaren.
Weiterhin müssen die Zeilen des Kommentars mit einem Sternchen als erstem Zeichen beginnen.
Es dürfen keine Leerzeichen oder andere Zeichen vor diesen Kommentarzeichen stehen!
Direkt nach dem Doxygen-Kommentar beginnt dann der Code, auf den sich der Kommentar bezieht.
Dies kann eine Funktion, eine Variable, eine Enummeration, usw. sein. Wichtig ist aber, dass zwischen Kommentar und Code keine Leerzeile steht!
Wenn man diese Stolperfallen berücksichtigt, sieht ein typischer Doxygen-Kommentar dann ungefähr so aus:
Code:
/**
* @SCHLÜSSELWORT BESCHREIBUNG
*/
SOURCECODE, AUF DEN SICH DER KOMMENTAR BEZIEHT
Daneben existieren jedoch auch noch andere Formen der Doxygenkommentarsyntax - eine Übersicht findet sich unter http://www.stack.nl/~dimitri/doxygen/docblocks.html

Schlüsselwörter werden mit einem @ oder Backslash \ gekennzeichnet und bezeichnen spezielle Eigenschaften des Codes oder Formatierungsoptionen.
An dieser Stelle ein ganz kurzer Überblick über die gebräuchlichsten Schlüsselwörter:
  • @brief - kurze Beschreibung des folgenden Codes
  • @param abc - Beschreibung des Parameters abc einer Funktion
  • @return - Beschreibung des Rückgabewertes einer Funktion
  • @class abc - Beschreibung der Klasse abc
  • @file abc.de - Beschreibung der Datei abc.de

Eine Übersicht über alle Schlüsselwörter findet sich unter http://www.stack.nl/~dimitri/doxygen/commands.html.

Ein Beispiel zu den Kommentaren

Um das nun etwas zu veranschaulichen, gehen wir nun Schritt-für-Schritt ein ganz simples Beispiel durch.
Zunächst brauchen wir ein kleines Javaprogramm, das es zu dokumentieren gilt:
Java-Code:
class Beispiel
{
  public static void main(String[] args)
  {
    System.out.println("Hello World!");
  }
}
Die Funktion dieses Programms ist vermutlich offensichtlich genug um sich Erklärungen hierzu zu sparen...

Doxygen wäre jetzt bereits in der Lage diesen Code zu dokumentieren - allerdings nur sehr oberflächlich.
Daher geben wir Doxygen nun noch ein paar Informationen über die main()-Funktion:
Java-Code:
class Beispiel
{
/**
* @brief Eine kurze Beschreibung der Funktion
*
* Eine detailliertere Funktionsbeschreibung
*/
  public static void main(String[] args)
  {
    System.out.println("Hello World!");
  }
}
Das Ergebnis in der HTML-Doku sieht dann etwa so aus:
Doku:
Dokumentation der Elementfunktionen

static void Beispiel.main ( String[] args ) [static]

Eine kurze Beschreibung der Funktion.

Eine detailliertere Funktionsbeschreibung

Definiert in Zeile 32 der Datei Beispiel.java.
Schon mal nicht schlecht. Jetzt geben wir Doxygen noch eine Beschreibung zur Klasse, in der diese Funktion verwendet wird:
Java-Code:
/**
* @class Beispiel
*
* @brief Eine kurze Beschreibung der Klasse
*
* Eine detailliertere Beschreibung der Klasse
*/
class Beispiel
{
/**
* @brief Eine kurze Beschreibung der Funktion
*
* Eine detailliertere Funktionsbeschreibung
*/
  public static void main(String[] args)
  {
    System.out.println("Hello World!");
  }
}
Der Text nach @brief sollte dabei die Funktion oder den Zweck der Klasse ganz kurz (in einem Satz) zusammenfassen, während eine detailliertere Beschreibung zwei Zeilen darunter erfolgen kann.
In der von Doxygen erstellten Dokumentation sieht das dann so aus:

Doku:
Eine kurze Beschreibung der Funktion. Mehr ...
Wobei man mit Klick auf Mehr ... zur ausführlichen Beschreibung geleitet wird.

Gut, wo wir jetzt schon dabei sind, können wir auch gleich noch eine Beschreibung zur Datei, welche den Code enthält schreiben:
Java-Code:
/**
* @file Beispiel.java
*
* @brief Eine kurze Beschreibung der Datei - was enthält sie, wozu ist sie da, ...
*
**/

/**
* @class Beispiel
*
* @brief Eine kurze Beschreibung der Klasse
*
* Eine detailliertere Beschreibung der Klasse
*/
class Beispiel
{
/**
* @brief Eine kurze Beschreibung der Funktion
*
* Eine detailliertere Funktionsbeschreibung
*/
  public static void main(String[] args)
  {
    System.out.println("Hello World!");
  }
}
Das Schlüsselwort hierzu lautet @file.
Bei solch einem simplen Beispielprojekt mit nur einer Codedatei mag der Sinn einer Dateibeschreibung zwar noch fragwürdig sein, sobald ein Projekt jedoch größer wird und aus mehreren Dateien besteht, ist diese Dokumentierungsfunktion zwecks allgemeiner Übersicht sehr nützlich, wie z.B. die Dateiendokumentation des Beispielprojektes mit den Sortieralgorithmen zeigt:

Hier folgt die Aufzählung aller Dateien mit einer Kurzbeschreibung:
DoxygenExample_de/DoxygenExample.java [code]Diese Datei enthält die DoxygenExample-Klasse mit der main()-Funktion
DoxygenExample_de/Paint.java [code]Diese Datei enthält die abstrakte Klasse Paint
DoxygenExample_de/sorting/BubbleSort.java [code]Diese Datei enthält die sorting.BubbleSort-Klasse
DoxygenExample_de/sorting/InsertionSort.java [code]Diese Datei enthält die sorting.InsertionSort-Klasse
DoxygenExample_de/sorting/SelectionSort.java [code]Diese Datei enthält die sorting.SelectionSort-Klasse
DoxygenExample_de/sorting/Sort.java [code]Diese Datei enthält die abstrakte sorting.sort-Klasse

Besonders praktisch an der HTML-Dokumentation: wenn man auf die blau markierten Dateinamen klickt (z.B. auf Paint.java), wird man direkt zur Dokumentation dieser Datei geführt.
Und mit Klick auf [code] gelangt man zum jeweiligen Quellcode.

Noch ein kleines Extra...

Im Grunde sind diese Schritte bereits ausreichend für eine vollständige Dokumentation - für den letzten Schliff fehlt aber noch ein kleines Extra: die Einstiegseite!
Bei der HTML-Dokumentation entspricht die Startseite der Datei index.html.
Diese sieht im Moment noch etwas spartanisch aus - außer Titel und Versionsnummer findet sich hier nicht viel.
Geben wir also Doxygen nun also noch ein paar Informationen über das Projekt:
Java-Code:
/**
* @mainpage Beispielprogramm
*
* Beschreibung des Projekts
* <br>Mit "<br>" kann bei der HTML-Dokumentation eine neue Zeile erzeugt werden
*
* Mit dem <img-Schlüsselwort können eigene Bilder hinzugefügt werden
* <img src="../application_screenshot.jpg" alt="Screenshot">
*
* @author Max Mustermann
*/

/**
* @file Beispiel.java
*
* @brief Eine kurze Beschreibung der Datei - was enthält sie, wozu ist sie da, ...
*
**/

/**
* @class Beispiel
*
* @brief Eine kurze Beschreibung der Klasse
*
* Eine detailliertere Beschreibung der Klasse
*/
class Beispiel
{
/**
* @brief Eine kurze Beschreibung der Funktion
*
* Eine detailliertere Funktionsbeschreibung
*/
  public static void main(String[] args)
  {
    System.out.println("Hello World!");
  }
}
Das Zauberwort lautet hier @mainpage und wird von einer Beschreibung des Projekts gefolgt.

So. Gerade bei der Projektbeschreibung auf der Einstiegseite ist ja nun die Optik oft sehr kritisch - der erste Eindruck ist am prägensten!
Also steigen wir zum Abschluss dieses Tutorials noch kurz etwas in die HTML-Materie ein.
Wer bereits HTML beherrscht, kann diesen Abschnitt getrost überspringen...

HTML-Layoutfunktionen in der Dokumentation

Wichtig: die folgenden Layoutschlüsselwörter funktionieren ausschließlich mit dem Doxygen-Ausgabeformat HTML.
Ist als Ausgabeformat z.B. RTF gewählt werden sie ignoriert oder führen zu unerwünschten Effekten.
  • Mit <br> wird ein neuer Zeilenabsatz erzwungen.

  • Mit <b> wird Fettschrift eingeleitet und mit </b> wieder beendet.

  • Mit <i> wird Kursivschrift eingeleitet und mit </i> wieder beendet.

  • Mit <ul> können Aufzählungen eingebunden werden. Die vollständige Syntax lautet:
    * <ul>
    * <li>Erstens</li>
    * <li>Zweites</li>
    * <li>Drittens</li>
    * </ul>
    Was dann zu einer Ausgabe folgender Art führt:
    • Erstens
    • Zweitens
    • Drittens
  • Mit dem <img-Schlüsselwort können eigene Bilder eingebunden werden. Gerade bei der Einstiegseite bietet es sich ja an, einen Screenshot der Anwendung einzubinden, was mit
    * <img src="../Bilder/application_screenshot.jpg" alt="Screenshot">
    erfolgt.
    Die Pfadangabe "../Bilder/" gibt Doxygen dabei an, dass sich die Bilddatei im Projektverzeichnis im Unterordner Bilder befindet.

Links und Dateien


Doxygen-Website
Graphviz-Website (DOT)

Beispiel Projekt (190 KB)
Doxygen 1.4.5 Download (5.4 MB)
Graphviz Download