C++-Programmierung: Dokumentation mit Doxygen

Das von Dimitri van Heesch entwickelte Werkzeug Doxygen erstellt aus den Quelltextdateien eine übersichtliche Dokumentation der Dateien, Klassen und Funktionen eines Softwareprojekts. Doxygen ist unter der GPL lizenziert und für die Betriebssysteme Linux, Microsoft Windows und Mac OS verfügbar.

Neben C/C++ unterstützt Doxygen weitere Programmiersprachen, z.B. Java und Python. Die Ausgabe kann in den Formaten HTML, LaTeX, Unix-Manpage u.a. erfolgen.

Auf der Doxygen-Homepage finden Sie eine ausführliche Anleitung, so dass wir uns hier auf die wesentlichen Aspekte beschränken können.

Installation

Doxygen kann als ausführbare Datei von der Doxygen-Homepage heruntergeladen werden. Unter Linux können Sie das Programm auch selbst kompilieren, wofür lediglich einige Standardwerkzeuge (gcc, make, flex, bison, perl) benötigt werden. Die grafische Oberfläche Doxywizard setzt Qt voraus. Damit optisch ansprechende Vererbungs- und Abhängigkeitsdiagramme gezeichnet werden können, muss das Programm dot aus dem Graphviz-Paket installiert sein.

Zusätzliche Tools

Um alle Funktionen von Doxygen verwenden zu können sind unter allen Plattformen zusätzliche Tools notwendig.

Windows

Doxygen ist in vielen Shells implementierbar, zB Cygwin.

Aufruf

Sie können Doxygen als doxygen von der Kommandozeile starten oder die grafische Bedienoberfläche Doxywizard benutzen. Weil beide Varianten unter der Oberfläche identisch funktionieren, genügt es, exemplarisch die Kommandozeilenversion zu besprechen. Der Aufruf

doxygen -g doxygen.config

erzeugt eine Konfigurationsdatei doxygen.config. Sie können diese mit instruktiven Kommentaren versehene Textdatei bearbeiten, um Doxygen allerlei Optionen mitzuteilen. Anschließend wird mit

doxygen doxygen.config

die Dokumentation erzeugt.

Wird die Konfigurationsdatei Doxyfile genannt, wird durch den Aufruf

doxygen

im selben Verzeichnis, wo sich die Konfigurationsdatei befindet, automatisch die Generierung der Dokumentation anhand der Konfiguration in der Datei Doxyfile gestartet.

Konfiguration

Die wichtigsten Abschnitte der Konfigurationsdatei sind:

Projekt (project related)

Hier geben Sie u.a. an, wo Doxygen die Doku platziert und in welcher Sprache sie erstellt wird:

OUTPUT_DIRECTORY = meine_doku
OUTPUT_LANGUAGE  = German 

Umfang (build related)

Hier stellen Sie z.B. ein, ob private Members in der Doku erscheinen sollen. Wichtig ist die Option

EXTRACT_ALL = YES

Mit YES erscheinen alle Klassen, Variablen, Funktionen usw. in der Doku, mit NO nur diejenigen, die einen speziellen Kommentar (s.u.) besitzen.

Eingabe (related to the input files)

Hier geben Sie an, welche Quelltextdateien Doxygen lesen soll.

Wichtige Optionen sind INPUT (wenn leer wird das aktuelle Verzeichnis benutzt) und RECURSIVE (ausgehend von INPUT in Unterverzeichnisse gehen)

 INPUT                  =
 RECURSIVE              = 

Quelltext (related to source browsing)

Hier kontrollieren Sie z.B., ob nur die Headerdateien oder auch die Implementationen in der Doku als Quelltext erscheinen sollen und nach welchen Regeln die Querverweise (bei HTML-Ausgabe die Hyperlinks) erzeugt werden.

Ausgabe (related to the XXX output)

Dieser Teil ist nach Ausgabeformaten in Unterabschnitte gegliedert. Z.B. teilen Sie Doxygen durch die Anweisungen

GENERATE_HTML       = YES
HTML_OUTPUT         = html
HTML_FILE_EXTENSION = .html

mit, dass die Ausgabe im HTML-Format erfolgen und ins Unterverzeichnis html geschrieben werden soll. Die HTML-Dateien erhalten die Endung .html

Präprozessor (related to the preprocesor)

Hier stellen Sie ein, ob und wie Doxygen Präprozessor-Direktiven expandieren soll.

Dot (related to the dot tool)

Hier bestimmen Sie, welche zusätzlichen Diagramme mit Hilfe von dot erzeugt werden sollen.

Spezielle Kommentare

Selbst wenn Sie dem Quelltext keine besondere Behandlung angedeihen lassen, erzeugt Doxygen eine nützliche Dokumentation, z.B. eine Liste aller Klassen, ein Vererbungsdiagramm, eine Liste aller Namen von Klassenelementen usw. Noch aussagekräftiger wird das Ergebnis aber, wenn Sie spezielle Kommentare in den Quelltext einfügen. Der C++-Compiler ignoriert diese wie alle anderen Kommentare auch, aber Doxygen übernimmt sie in die Ausgabe. Das geht sogar zweistufig: Sie können jeweils eine kurze und eine ausführliche Beschreibung angeben. In C++ schreibt man spezielle Kommentare am besten so:

/// spezieller Kommentar kurz: klasseA macht dies und das
/** ausführliche Beschreibung der klasseA
    usw. usw. */
//  normaler Kommentar, wird von Doxygen ignoriert
class klasseA {
  // Klassendeklaration ...
};

Die Kommentarblöcke stehen normalerweise unmittelbar vor der Deklaration der Klasse, Variablen, Funktion usw., auf die sie sich beziehen. Doxygen ist hier aber nicht anspruchsvoll, wie Sie an diesem Beispiel sehen:

class klasseA {
private:
  /// Kurzbeschreibung Variable a
  /** Langbeschreibung Variable a */
  int a;
  /** Kurzbeschreibung Variable b geht bis zum Punkt. Was jetzt
   *  kommt, ist die ausführliche Beschreibung.
   */
  int b;
public:
  int f(int); ///< Kurzbeschreibung Funktion f
  int g();    /**< Langbeschreibung Funktion g */
  // ...
};

Lauter gleichwertige Methoden, um spezielle Kommentare anzugeben. Achten Sie auf das <, wenn Sie den Kommentar hinter die Memberdeklaration schreiben!

Übrigens gibt es auch die Möglichkeit, Kommentarblöcke und Code zu trennen, indem Sie in den Kommentaren Doxygen-Schlüsselwörter wie \class, \struct usw. verwenden.

Hoch zu Inhaltsverzeichnis