Doxygen: Eine frische Brise für automatisierte Programm-Dokumentation

Der beste Weg, Doxygen kennen zu lernen, ist die -g Option. Damit gibt man dem Tool die Anweisung, eine Vorlage für eine Konfigurationsdatei zu erstellen. Man kann auch den Doxywizard verwenden, anstatt eine Konfigurationsdatei von Hand zu erstellen. Es gibt allerdings eine sehr große Anzahl von Optionen, die dort verändert werden können, so dass man schnell den Überblick verlieren kann. Erklärungen über alle verfügbaren Optionen finden sich im ausführlichen Handbuch.

Standardmäßig ignoriert Doxygen normale Kommentare, obwohl man eine Einbindung mit Hilfe der Konfigurationsdatei erzwingen kann. Doxygen verwendet zwei Arten von Kommentaren: kurz und detailliert. Kurze Kommentare sind, wie sie sich nennen: kurz. Diese einzeilige Beschreibungen eines Codeabschnittes, die durch einen extra Slash bezeichnet werden oder mit einem Ausrufezeichen in C-artigem Einzeilenkommentar, sehen so aus:

Auf der anderen Seite können sich detaillierte Kommentare über mehrere Zeilen erstrecken und sind für detailreichere Beschreibungen gedacht. Diese werden erzeugt, indem man ein Ausrufezeichen zu einem multiline comment indicator hinzufügt:

Das JavaDoc multi-line Format (/** … */) kann ebenfalls benutzt werden. Die zwei Kommentartypen tauchen an verschiedenen Stellen in der erzeugten Dokumentation auf. Es gibt ein ausgezeichnetes Beispiel einer Dokumentationsseite, die aus einem simplen C++ Programm erzeugt wurde, weshalb ich es an dieser Stelle nicht wiederholen werde. Sollte man mehr Komplexität benötigen, ist Doxygen in der Lage, fortgeschrittenere Formatierungen wie Gruppen und Listen zu erzeugen. Man kann jedoch mit den beiden diskutierten, grundlegenden Arten von Kommentaren absolut brauchbare Dokumentationen erstellen kann.

Nachträgliche Dokumentation
Die Dokumentationsmöglichkeiten von Doxygen sind hiermit keinesfalls erschöpft. Doxygen kann auch farbige Mehrfachvererbungsdiagramme direkt aus dem Quellcode grafisch darstellen. Mit dem Tool eines Drittanbieters (dot) können diese Diagramme recht komplex gestaltet werden. Besonders die Fähigkeit, vorhandenen Quellcode zu analysieren, macht Doxygen hilfreich – so kann man undokumentierten Code von anderen besser verstehen – und wie oft findet man undokumentierten Code? Wieder einmal ist das Online-Benutzerhandbuch das beste Beispiel für die Diagrammarten, die Doxygen erzeugen kann.

Doxygen ermöglicht fortgeschrittene Generierung von Dokumentation in der Art, in der JavaDoc sie in die Welt der C++- und C#-Programmierer gebracht hat. Die Möglichkeit, Quellcodeblöcke und normale Kommentare einzubinden, um dann mühelos Dokumentationen in unterschiedlichen Formaten zu erstellen, bringt willkommene Flexibilität für ein Tool, das einfach zu handhaben und dennoch sehr mächtig ist.