Doxygen im Jahr 2024: Noch Standard für C++-Dokumentation oder Zeit für neue Ansätze?

Stärken von Doxygen

Doxygen erkennt fehlende und überflüssige Funktions-Dokumentation und warnt den Entwickler entsprechend. Zudem erstellt Doxygen verschiedene Diagramme (Klassen-Diagramm, Kollaboration- Diagramm, Call-Graphs, …) basierend auf dem analysierten Source code.

Nebst den Kommentaren im Source Code, lässt Doxygen Sie auch High Level Dokumentation schreiben und aus dieser auf Source Code zu referenzieren. Die Liste von großartigen Features geht noch weiter – es gibt vieles an Doxygen was wir lieben, dennoch gibt es einige Herausforderungen.

Herausforderungen

1. Die von Doxygen generierte HTML-Dokumentation wirkt oft altbacken und entspricht nicht den heutigen Webdesign-Standards. Dies kann dazu führen, dass die Benutzererfahrung für Entwickler und andere Stakeholder beeinträchtigt wird.
   
   
2. Bei komplexen C++ Codeabschnitten stösst Doxygen manchmal an seine Grenzen und interpretiert den Source-Code nicht korrekt. Dies kann zu unvollständiger oder fehlerhafter Dokumentation führen. Entwickler müssen in solchen Fällen Workarounds verwenden, z. B. durch das Setzen von #ifdef DOXYGEN-Bedingungen, um spezifische Teile des Codes nur für die Dokumentation sichtbar zu machen oder davon auszuschliessen.
   
   

Alternativen zu Doxygen

Gibt es denn Alternativen zu Doxygen?

Und zwar nicht Alternativen die uns schöne, statische Websites aus Markdown oder rst Dateien erstellen und uns so natürlich Dokumentation schreiben lassen, sondern Alternativen die effektiv den Source-Code analysieren und daraus eine Dokumentation erstellen.

Leider sind Dokumentations-Tools, welche den Source-Code parsen und daraus Dokumentation erstellen rar. Grund dafür ist wohl, dass das Parsen von C++ schwierig ist, sehr schwierig sogar.

Es gibt Standardese, welches das ambitionierte Ziel hat das nächste Doxygen zu werden. Es gestaltet die Code-Dokumentation ähnlich wie in der Standard C++ Library reference, was nach einem grossartigen Ansatz klingt. Leider hat Jonathan Müller, der Hauptentwickler von Standardese, das Projekt verlassen. Obwohl es nun unter der GitHub-Organisation “standardese” weiterentwickelt wird, steht noch kein stabiles 1.0-Release zur Verfügung.

Nicht eine Alternative aber eine Erweiterung zu Doxygen ist Spexygen. Dies basiert auf Doxygen und ermöglicht Anforderungen mit Source-Code und Tests zu verlinken. Gerade für Anwendungen im regulatorischen Bereich hat die Traceability eine hohe Relevanz.

Den praktischen Einsatz von Spexygen in einem Kundenprojekt haben wir noch nicht realisiert.

Tipps für die Verwendung von Doxygen

Es scheint also, dass Doxygen im Moment wirklich der defacto Standard ist. Daher nachfolgend einige Tipps wie wir Doxygen gewinnbringend einsetzen können.

• Modernes Erscheinungsbild: Als Abhilfe für die altmodische HTML-Dokumentation können wir Doxygen Awesome empfehlen. Ein modernes Theme für die Doxygen HTML Dokumentation, welches sich einfach integrieren lässt.
  
  
• High Level Dokumentation: Organisieren Sie die Teile, welche nicht direkt Source-Code beschreiben in Seiten und Unterseiten. Referenzieren sie bei Bedarf auf Namespaces oder Gruppen.
  
  
• Strukturierung: Achten sie bei der Organisation von Seiten und Unterseiten auf eine für den Leser logische Strukturierung.
  
  
• Source-Code Dokumentation: Dokumentieren Sie den Source-Code auf Namespace-Ebene und Klassen-Ebene. Dies hat den Vorteil, dass nicht nur die Dokumentation gut strukturiert ist, sondern auch der Source-Code. Beachten Sie, dass Doxygen nicht vor undokumentierten Namespaces warnt. Verwenden Sie Gruppen nur dort, wo Namespaces nicht möglich sind (z. B. bei Legacy-C-Code).
  
  
• Alles dokumentieren: Bauen Sie ein `@file` in den Boilerplate all Ihrer Source-Dateien ein. Dies hilft zu verhindern, dass ganze Dateien versehentlich aus der Dokumentation ausgeschlossen werden.
  
  
• Dokumentation aktuell halten: Integrieren sie das builden der Dokumentation in ihre CI-Pipeline und fordern sie diese in PRs ein. Dadurch kann die Aktualität und somit die Brauchbarkeit der Dokumentation erhöht werden.
  
  
• Beispiel: Wir erachten die Dokumentation von QP/C++ als ein gutes Beispiel für eine gut strukturierte Source-Code Dokumentation.
  
  

Fazit

Doxygen ist seit Jahren der Platzhirsch in Sachen Codedokumentation. Vielleicht besteht kein Interesse in der Open-Source Community diesen Sachverhalt zu verändern, vielleicht ist das Analysieren von C++ Code einfach zu schwierig.

Auf jeden Fall konnte sich die mögliche Alternative “Standardese” noch nicht durchsetzen. Bis dahin verwenden wir von CSA Engineering AG weiterhin Doxygen und sind natürlich gerne bereit Sie bei der Dokumentation von Ihrem Source-Code zu unterstützen.

Sorgen Sie für klare Strukturen in Ihrem Code und setzen Sie auf eine verlässliche Dokumentation. Sprechen Sie mit uns – wir begleiten Sie bei jedem Schritt und schaffen nachhaltige Lösungen, die Ihre Entwickler entlasten und die Wartung erleichtern!

Zum Kontaktformular >