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
BearbeitenDoxygen 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
BearbeitenUm alle Funktionen von Doxygen verwenden zu können sind unter allen Plattformen zusätzliche Tools notwendig.
Windows
BearbeitenDoxygen ist in vielen Shells implementierbar, zB Cygwin.
MikTeX
BearbeitenGraphViz
BearbeitenLinux
BearbeitenAufruf
BearbeitenSie 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
BearbeitenDie wichtigsten Abschnitte der Konfigurationsdatei sind:
Projekt (project related)
BearbeitenHier 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)
BearbeitenHier 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)
BearbeitenHier 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)
BearbeitenHier 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)
BearbeitenDieser 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)
BearbeitenHier stellen Sie ein, ob und wie Doxygen Präprozessor-Direktiven expandieren soll.
Dot (related to the dot tool)
BearbeitenHier bestimmen Sie, welche zusätzlichen Diagramme mit Hilfe von dot erzeugt werden sollen.
Spezielle Kommentare
BearbeitenSelbst 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.