On Sat, Feb 27, 2016 at 10:28 AM, Paul A. Bristow
No - you are absolutely correct that this isn't much help and is why Doxygen has a bad reputation with some.
People have the totally misguided impression that just running Doxygen on the header files is a 'job done'.
That's entirely wrong - they haven't even started the job!
You have to document what the classes, functions, macros, templates and files actually do!
describing their preconditions, post conditions, throws or not ... and for this there is a de facto standard that I call the Doxygen syntax. It provides categories like \pre \post \return \param \tparam \throw ... and a simple mark-up language, including code sections with syntax coloring etc.
Soon, the Clang compiler will be able to process these comments for Doxygen (rather than using its own struggling-with-fancy-C++-templates parser) and emit the results in a useful way.
When this is done, the C++ reference section immediately becomes invaluable because you can click on each item like a function or class and read what is does. Index(es) also takes you straight to the item. (And you can read the comments as you go if you are reduced to reading the header file itself).
All this is hard work (and very tedious if done retrospectively) so few people have done it properly yet.
For future-proofing, the vital information is stored in a standard-ish way, so it can be processed by other tools to give your preferred look'n'feel, SGI-ish if you like that (or not, if like me, you hate it).
I couldn't agree more with you comment.