Why we still use Doxygen (just not the way you think)
Doxygen isn't dead. The default output is. Here's how we turn it into docs users actually read.
Last month at a Write the Docs Barcelona meetup, someone asked me: “Do you see tools like Doxygen going out of style?”
The team works in different languages, deals with different tools to extract code comments, and ends up with Doxygen output that looks vintage. The default HTML lives as a separate site with its own search, its own navigation, no easy way to make it match the rest of the docs. So even when they publish it, nobody reads it.
Here’s how we work around it.
The problem isn’t Doxygen
Doxygen is great at the part most people don’t want to do themselves: parsing code comments and extracting structured information. Class hierarchies, function signatures, parameter descriptions, return types, defaults. It works across C++, Java, and a long list of other languages.
The problem is what comes out of the box. The HTML looks like it was built two decades ago. It can’t be styled to match your navigation. It uses its own search bar, separate from the main one users already know. It feels like a different product altogether.
So engineers close the tab. Writers stop pushing for it. The reference docs either don’t get published, or they get published and nobody reads them. Neither is good.
Use Doxygen as a parser, not a publisher
Doxygen also generates XML alongside HTML. Same structured data, just in a format you can do something with.
From that XML you can produce markdown, RST, or whatever format your docs platform expects. The API reference becomes part of your docs instead of a separate site bolted on. Sphinx, Docusaurus, Antora, MkDocs, whatever you’re already using.
The big shift is control. You decide how the reference looks. You can hide internal helpers Doxygen would otherwise expose, like for example group classes by feature instead of file. Strip out the noise (private members, autogenerated boilerplate, deprecated APIs nobody uses) and only show what your users actually need. None of that is possible with the default HTML.
We did this for ScyllaDB’s Driver docs. Built a custom extension that consumed the Doxygen XML and rendered it as native Sphinx pages.
The API reference now looks like every other page on the site. Same theme, same navigation, same search. When the team adds new libraries, the reference updates from the comments in the code, automatically.
The downside is that you have to write the extension if one doesn’t exist for your platform. But that’s a one-time effort, and the alternative is maintaining reference docs by hand and watching them go stale every release.
Why this matters more now
Structured API reference is also exactly what AI agents need to write correct code. When an agent has to know what parameters a function takes, or what its return type is, the reference is more reliable than any tutorial. It comes straight from the source.
Doxygen’s XML already contains all of that. Publishing it properly means it’s useful for both humans and AI, not just one or the other.
So is Doxygen going out of style?
The template is. The tool isn’t. Doxygen still does the hardest part: extracting structured documentation from code.
Throw away the HTML. Keep the XML.