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

Eine Dokumentation zu schreiben, ist eine ziemlich schwierige Aufgabe. Was für eine Erklärung sollte es sonst für die Tatsache geben, dass einige Unternehmen einen oder vielleicht mehrere Mitarbeiter bezahlen, deren einzige Arbeit die Dokumentation ist? Eines Tages fragte ein Java-Entwickler: „Wie wäre es, wenn wir ein Tool entwickeln, das die Dokumentation für unsere Kommentare im Quelltext generiert?“ Damit war JavaDoc geboren. Heute haben C#-Entwickler auch etwas Ähnliches dazu in Form von XML-Kommentaren. Aber was ist mit C++-Programmierern? Sind sie dazu verdammt ihre Dokumentationen auf die alte Art und Weise zu erstellen? Nicht mit Doxygen.

Doxygen kann mit allen auf C basierenden Programmiersprachen verwendet werden, wie C++, C, IDL, Java und sogar C# oder PHP. Neben der Tatsache, dass Doxygen offen und nicht proprietär ist, unterscheidet es sich auch von kommerziellen Produkten wie JavaDoc, indem es integrierte Unterstützung für eine breitgefächerte Anzahl von Formaten bietet. Zusätzlich zu HTML können für LaTeX, PDF, RTF, PostScript, compressed HTML (Microsoft HTML Help-kompatibel) und sogar für UNIX man page-Formate Dokumentationen erstellt werden. Doxygen ist sogar flexibel genug, um Dokumentationsdateien auf Benutzerebene zu erstellen: Auch das Doxygen-Benutzerhandbuch wurde mit Doxygen selbst geschrieben, in Augen des Entwicklers gleicht dies fast schon einer Misshandlung. Doxygen beinhaltet sogar einen eingebauten C Macro Preprocessor.

Vielseitig und mächtig

Beim ersten Durchblättern des Handbuchs kann Doxygen erschreckend kompliziert wirken. Dieser Eindruck wird nicht immer bestätigt – man kann die Dinge so kompliziert oder so simpel gestalten, wie man will. Doxygen ist überraschend vielseitig.

Um eine einfache Dokumentation zu erstellen, muss man nur ein wenig über Arten von Kommentaren wissen. Wer irgendwann JavaDoc verwendet hat, dem wird einiges bekannt vorkommen. Wenn die Anforderungen komplexer werden, kann man auf spezielle Formatierungsfähigkeiten zurückgreifen, um besonders formatierte Listen oder Diagramme in die Dokumentation mit einzubinden – oder sogar um Blöcke von Quellcode einzubinden. Letzteres ist hilfreich für Kommentare von Kollegen oder um die interne Struktur einer Anwendung zu dokumentieren.

Doxygen verwendet eine textbasierende Konfigurationsdatei, in der man eine Vielzahl von Optionen steuern kann, um das Verhalten des Programms zu beeinflussen. File und directory pattern matching werden unterstütz, somit kann man kontrollieren, welche Quelldateien Doxygen untersucht. Des Weiteren gibt es eine rekursives Suchfunktion für Verzeichnisse, die in der Konfigurationsdatei genauer definiert werden kann. Da Doxygen den Dateinamen der Konfigurationsdatei als Kommandozeilenparameter erwartet, ist es möglich und empfehlenswert, für mehrere Projekte mehrere Konfigurationen zu erstellen. Wenn man die Textdateien nicht von Hand bearbeiten möchte, präsentiert sich der vorhandene Doxywizard mit einem GUI-Interface, hier kann man die Konfigurationsdatei modifizieren.