Doxygen: generating C++ API documentation from annotated sources

What problem Doxygen solves, and for whom

Source comments and published documentation drift apart because they live in different files edited by different people. Doxygen can extract documentation from source comments and can also include separate documentation files. It parses annotated sources and generates the reference material from them, so the documentation is extracted directly from the sources, which the README describes as making it much easier to keep the documentation consistent with the source code. That is the whole proposition, and it is a narrow one.

The tool is aimed at people maintaining codebases large enough that a reader cannot hold the structure in their head. The README names C++ first and calls Doxygen the de facto standard for that language, then lists C, Objective-C, C#, PHP, Java, Python, IDL in several flavors, Fortran, some support for D, and VHDL. If you write in one of those languages and your team already writes structured comments, Doxygen is the obvious candidate. If your code has no comments, the second use case in the README applies: extract the code structure from undocumented source files, which it calls useful to quickly find your way in large source distributions. That is a browsing aid, not documentation.

How Doxygen turns annotated sources into HTML and LaTeX

The README describes three ways Doxygen can help. The primary one is an online documentation browser in HTML, optionally paired with an offline reference manual in LaTeX. Beyond those, the README lists RTF (MS-Word), PostScript, hyperlinked PDF, compressed HTML, DocBook and Unix man pages. The documentation is extracted directly from the sources rather than written separately.

The second mechanism is structural extraction. Doxygen can pull the code structure out of sources that carry no documentation comments, and it can visualize relations between elements through include dependency graphs, inheritance diagrams and collaboration diagrams, all generated automatically. Those diagrams depend on external tooling at runtime; the repository Dockerfile installs graphviz in the final image, which tells you what the maintainers consider necessary for a working deployment.

The third use is documentation for its own sake. The README notes that Doxygen was used to build the Doxygen user manual and website. That is a useful signal about scope: the tool is not limited to API reference, though API reference is what most people use it for. The repository layout reflects the split. The top level has doc/ and doc_internal/ directories, and examples/ contains paired .cfg configuration files and source files such as afterdoc.cfg with afterdoc.h, author.cfg with author.cpp, and diagrams.cfg with a set of diagrams_a.h through diagrams_e.h headers. Those pairs are the closest thing to a worked example set in the repository.

Installing Doxygen and running a first generation pass

The README does not give install commands. It points to the installation section of the manual at https://www.doxygen.nl/manual/install.html and to https://www.doxygen.nl/ for the latest binaries and source code. That is where platform-specific instructions live, and it is the only install guidance the README provides. The repository also carries an INSTALL file and BUILD.txt at the top level for building from source, and a Dockerfile if you would rather not install anything on the host.

The Dockerfile is a two-stage build. The builder stage starts from ubuntu:jammy, installs g++, python3, cmake, flex and bison, copies the repository into /doxygen, then runs cmake with the Unix Makefiles generator followed by make and make install. The final stage starts from ubuntu:jammy, installs graphviz, copies the built binary from /doxygen/build/bin/doxygen to /usr/local/bin/, and sets the entrypoint to doxygen. The consequence is that the container expects a configuration file and source tree to be mounted or copied in, because the working directory is /doxygen and the entrypoint takes Doxygen arguments directly.

The repository's examples directory pairs each .cfg configuration file with the source it documents. Reading a pair together shows the relationship between configuration and output without guessing. The README does not state where generated output lands, so read the configuration file rather than assuming a directory name. If you use the container, arrange the working directory and mounted paths so that Doxygen can see both the configuration file and the sources. The Dockerfile is the one build path that installs the build dependencies for you.

Where Doxygen is the wrong tool

The README is candid about language support being uneven. C++ is the primary target. Python, Java, C#, PHP, Fortran and the IDL flavors are listed as supported. D gets "to some extent". VHDL support is mentioned without qualification. That gradient matters: a polyglot repository will get better output for the C++ half than for the rest, and the quality of extraction for a language Doxygen only partly understands is not something the README promises.

A second boundary is conceptual. Doxygen extracts. It does not explain. If your code is undocumented, the structural extraction mode gives you include dependency graphs and inheritance diagrams, which help you orient in an unfamiliar tree but answer none of the questions a new contributor actually asks. Teams sometimes adopt Doxygen expecting the generated site to substitute for written architecture notes. It will not.

A third issue is that comment conventions are load-bearing. The examples directory is built around specific comment styles, and the manual is the authority on which markers produce which output. If your codebase uses an idiosyncratic comment format, you are signing up for either a migration or a configuration exercise, and the README says nothing about automatic conversion. There is also no rollback story in the README for generated output; it is a build artifact you regenerate or discard.

Doxygen against Sphinx, and why the split exists

The natural alternative for Python-heavy and mixed-language projects is Sphinx, which is built around reStructuredText or Markdown source files rather than comments embedded in code. The difference in approach is where the text lives. Sphinx treats documentation as a document you write, with code references pulled in through extensions. Doxygen can extract comments from code and also include standalone Markdown pages.

That difference decides the choice more than any feature list. If your team already writes substantial prose in .rst files, Sphinx matches the existing workflow. Keeping comments near code can make updates easier, though comments and behavior can still drift apart. The README lists no XML output, so any pipeline that feeds Doxygen output into other tools is something to verify in the manual rather than assume.

Licence and the cost of keeping up

Doxygen is licensed under GPL-2.0, per the repository's LICENSE file and the project metadata. That is a copyleft licence. If you run Doxygen as a build tool and publish the generated HTML, the generated output is not the program, but the question of what obligations attach to a build tool in your pipeline is one for your own legal review. This article does not give legal advice, and the README does not discuss licence implications at all, which is itself worth noting for a tool this widely embedded in build systems.

On maintenance, the repository is not archived and the last push was on 2026-11-01. Releases are regular: 1.16.1 on 2026-01-11, 1.17.0 on 2026-04-30, and 1.18.0 on 2026-08-13. Upgrade cost is mostly configuration drift. Doxygen configuration files are long and version-sensitive, and a generated configuration file from an older release may carry options that changed meaning or disappeared. The practical approach is to regenerate the configuration against the new binary and diff it against your current file, rather than upgrading the binary alone and hoping the old configuration still behaves the way you expect.

Editorial conclusion

Adopt Doxygen if your project already carries structured comments and you need HTML, LaTeX, RTF, DocBook or man page output generated from the same files. Do not adopt it if you expect it to infer intent from undocumented code: the README states it can extract structure from undocumented sources, but the prose still has to come from somewhere. Before committing, verify that your comment style matches what the manual describes, and check the install section at https://www.doxygen.nl/manual/install.html against your platform.

Frequently asked questions

Official sources

1. doxygen/doxygen on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases