Doxygen in 2024: Still the standard for C++ documentation or time for new approaches?
Doxygen as the de facto standard for the documentation of C++ code persists even in 2024.
But why is this the case, and what alternatives are available? Let's take a closer look.
Doxygen is a reliable tool that has been around for 26 years and is constantly being developed further. It can generate not only C++ code but also documentation for further languages such as C, Python, PHP, C#, Fortran, and others.
Doxygen allows you to document your source code in a structured way. One function is provided with comments directly in the code (figure 1), which are interpreted and rendered by Doxygen - for example as an HTML page (figure 2).
Figure 1: Method with Doxygen comments
Figure 2: HTML page rendered by Doxygen
Strengths of Doxygen
Doxygen recognizes missing and superfluous function documentation and warns the developer accordingly. In addition, Doxygen creates various diagrams (class diagrams, collaboration diagrams, call graphs, ...) based on the analyzed source code.
In addition to the comments in the source code, Doxygen lets you write high-level documentation and reference source code from it. The list of great features goes on. There are many things we love about Doxygen, but there are still some challenges.
Challenges
- The HTML documentation generated by Doxygen often looks old-fashioned and does not meet today's web design standards. This can lead to a poor user experience for developers and other stakeholders.
- With complex C++ code sections, Doxygen sometimes reaches its limits and does not interpret the source code correctly. This can lead to incomplete or incorrect documentation. Developers must use workarounds in such cases, e.g. by setting #ifdef DOXYGEN conditions to make specific parts of the code visible only to the documentation or to exclude them from it.
Alternatives to Doxygen
Are there alternatives to Doxygen?
And not alternatives that create beautiful, static websites from Markdown or rst files and let us write documentation naturally, but alternatives that effectively analyze the source code and create documentation from it.
Unfortunately, documentation tools that parse the source code and build the documentation from it are rare. The reason for this is probably that parsing C++ is challenging.
Standardese aims to be the next generation of Doxygen, offering code documentation styled like the Standard C++ Library reference—a promising concept. However, with its primary developer, Jonathan Müller, stepping away, the project has shifted under the GitHub organization “standardese.” While development continues, a stable 1.0 release is still pending.
Spexygen is not an alternative but an extension of Doxygen. This is based on Doxygen and enables requirements to be linked with source code and tests. Traceability is particularly relevant for applications in the regulatory area.
We have not yet realized the practical use of Spexygen in a customer project.
Tips for the use of Doxygen
So it seems that Doxygen is the de facto standard at the moment. Here are some tips on how to use Doxygen profitably.
- Modernize the look: To give your HTML documentation a fresh, updated appearance, we recommend using Doxygen Awesome—a sleek, modern theme for Doxygen that’s simple to integrate.
- High-level documentation: Organize the parts that do not directly describe source code into pages and subpages. If necessary, reference namespaces or groups.
- Structuring: When organizing pages and subpages, ensure that they are structured logically for the reader.
- Source code documentation: Document the source code at the namespace level and class level. This has the advantage that not only the documentation is well structured, but also the source code. Note that Doxygen does not warn against undocumented namespaces. Only use groups where namespaces are not possible (e.g. legacy C code).
- Document everything: Include a `@file` in the boilerplate of all your source files. This helps to prevent entire files from being inadvertently excluded from the documentation.
- Keep documentation up to date: Integrate its generation into your CI pipeline and make it a requirement in pull requests. This approach ensures your documentation stays up-to-date and enhances its usability.
- Example: We consider the QP/C++ documentation to be a good example of well-structured source code documentation.
Conclusion
Doxygen has been the leading tool for code documentation for years, and it seems the open-source community hasn’t shown much interest in changing that. Perhaps the complexity of analyzing C++ code plays a role.
Currently, alternatives like "Standardese" have struggled to gain widespread adoption. At CSA Engineering AG, we continue to rely on Doxygen and are happy to assist you with documenting your source code efficiently and effectively.
Ensure clean, well-structured code and robust documentation. Partner with us, and we’ll support you every step of the way—delivering sustainable solutions that lighten the load for your developers and simplify ongoing maintenance!
Pascal Hari
BSc BFH in Microtechnology
Embedded Software Engineer
About the author
Pascal Hari has been working as an embedded software engineer at CSA Engineering AG for 6 years. His focus is on developing firmware in C++ on STM32.
He appreciates and contributes to a well-documented SW project. In recent years, he has created several platforms and project documentation in Doxygen.