Doxygen should be replaced with rendered comments in IDEs/code editors. That's the real solution.
The user should visit docs to get to know a high-level overview of a library or human-readable explanation of an algorithm. Not to see stuff that's already explained by the code itself.
So here I threw away all this noise and the theme is actively forcing the library authors to focus on important stuff in the docs, explicitly excluding useless things that could be auto-generated. "Installing Doxygen on a project" achieves nothing, one has to write the actual docs first.
The result? See for yourself: https://doc.magnum.graphics/magnum/namespaceMagnum_1_1Animat...
There's a lot of value in shaping/limiting options and choices to make Doxygen easier to use for focused, high-quality external docs, but I'm not sure it follows that the other information it can generate is useless.
But the fact that you haven't heard from the inevitably short list of projects that have looked for new documentation tools in the past ~14 months and also happen to be complex enough to benefit from niche features like inheritance diagrams doesn't mean they don't exist.
If you look at other languages, automatically-generated code documentation has become the main way people ingest documentation for software projects. Javadoc was the first major such tool; if I'm trying to use a Java library, I don't read the source code, I start by reading the generated documentation. If you've ever used https://docs.oracle.com/javase/8/docs/api/, you've used the results of Javadoc. Similarly, Rust also has a widely-used builtin documentation tool (and again, the official standard library documentation is entirely the result of rustdoc).
C/C++ of course don't have a builtin tool. Doxygen attempts to fulfill that same gap, but it also suffers from trying to support every language under the sun, as well as the inherent issues of C/C++ (the use of the preprocessor to generate module boundaries does not make for fun processing). I also find that the default settings tend to make too many graphs that aren't really useful but take up a lot of visual space (I've never found collaboration graphs to be helpful), and its approach to trying to figure out what things are types gets pretty sketchy (why does it think that unsigned is a class?). To top it off, I was never impressed with its design aesthetic.
In short, the fault of doxygen is that it's not designed in close integration with the language parser to ensure a highly correct understanding of source code, which makes it tend to fall over if anything is moderately unusual or confusing. And since the general experience with its output tends to be negative, there isn't much effort in trying to maintain quality documentation comments in the underlying code in the first place.
There's nothing inherently wrong with the code Doxygen generates or with its C++ parser. I've worked on large projects using crazy Boost pre-processor macros and plenty of C++14 features and Doxygen handled it all fine.
IME the number one problem with Doxygen is that the people writing the doc comments do a poor job. It's garbage in, garbage out.
The Java documentation is great because the people who write it put in a ton of effort to actually explain how to use their API, with examples, hyperlinks to other modules, version information, compatibility issues, and everything else. They're not adding trivial @param and @return comments as an afterthought.
Unfortunately, a lot of Doxygen documentation seems to be the trivial kind that tells you "@param foo The integer parameter foo" but doesn't give any clue how to use the library, class, or method.
That's just the stuff I have readily available; there's been several times where I tried to use Doxygen to figure something out, only to discover that it was horribly confused and worse than useless (since it looks like it can tell you the information, but it doesn't figure it out).
I'm fairly certain that doxygen uses libclang for a correct parse of the code these days.
Note that to be useful someone needs to their full time job to edit it and make sure there are good examples.
I haven't converted much of my documentation to doxygen yet, so I'm not sure how well it works in practice but so far it seems like a promising approach.
Also, when you work with OO junkies features like INLINE_INHERITED_MEMB create some useful and much more navigable projections.
I think it would be very interesting if e.g. Sphinx were able to generate pages where the highlighted and crossreferenced code is interleaved with the processed markup from those parts it extracts today (docstrings etc.). Heck, even being able to just tell it to only generate the source code pages and crossref to those instead would be better for documenting applications.
Btw., I'm now working on a C# support for this documentation theme, but by using XMLDoc directly instead of Doxygen (and thus also with none of its bugs). See here: https://github.com/mosra/m.css/issues/76
For the IDE docs integration, I know about QHP (by Qt), which is supported by QtCreator, KDevelop and has a VS support using the Qt VS Tools plugin. But that's C++. Weird that VS doesn't have something similar builtin for C#...
What needs to be in comments (and frequently isn't IME) is intent.
edit: actually there seems to be an extension for Visual Studio for example: https://marketplace.visualstudio.com/items?itemName=MsBishop...
I feel silly for never searching for that ... but then unlike with Doxygen everyone needs to have that extension
I agree it's usually not the best tool for generating outward-facing API documentation for languages with native documentation tools (though mosra is demonstrating that it's not incapable).
With several different configs, however, Doxygen can generate different docsets that can be tailored to multiple audiences that need to understand different sections and facets of a sprawling codebase.
Even more impressive considering it's a C++ project.
Especially because (if I can dare to say) I ended up with a much better search than what Sphinx (or Doxygen) has -- try it out: https://doc.magnum.graphics/magnum/?q=max#search ;)