Re:Improved Doxygen documentation and search for C++ projects
by Something1234 on Thursday January 03, 2019 @10:38PM
(#18821775)
I find the caller and callee stuff kind of useful if I'm handed a legacy project that is kind of well structured I can get an overview of the code flow.
Re:Improved Doxygen documentation and search for C++ projects
by abathur on Thursday January 03, 2019 @02:32PM
(#18818400)
Doxygen can generate a lot of data most projects don't need (and may not have the best defaults). Especially for external docs.
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.
Re:Improved Doxygen documentation and search for C++ projects
by mosra on Thursday January 03, 2019 @03:01PM
(#18818690)
For the record, nobody complained when I removed all the class diagrams and other things mentioned above, so my takeaway was that ... yes, those features were useless :) On the other hand, people complained about lack of essential features that Doxygen didn't have, like proper search or #include information for non-class members.
Re:Improved Doxygen documentation and search for C++ projects
by abathur on Thursday January 03, 2019 @05:00PM
(#18819732)
Sure. You're doing useful work shaping something that is a bit too free-form for most. I didn't question your curation. Nor do I think your project needs to support them.
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.
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...