You know what really grinds my gears? Something which seems to be more and more common nowadays? Huge open source utility libraries which are completely undocumented, except for a Doxygen-autogenerated "documentation".
I think that the Doxygen homepage itself summarizes this practice the best:
You can even `abuse' doxygen for creating normal documentation
Doxygen-generated files are not normal documentation (although, with trickery, you can abuse it to try to do it, as its homepage puts it).
What Doxygen generates is a reference manual for the public interface of the library. In practice this reference manual is just a more convenient way of browsing the (preferably commented) header files of the library, and little else.
This is great when you are already very fluent at using the library, and only need a reference manual for the details. It's in no way a substitute for real documentation on how the library is used.
That's the basic difference between a reference manual and a documentation: A reference manual is simply a systematic listing of public interface methods with comments. A documentation, on the other hand, contains higher-level instructions on how to actually use the library. These instructions include things like first-time tutorials and how-to's.
It seems that more and more libraries out there go the lazy path of simply providing Doxygen-generated reference manuals and nothing else. Can't these developers understand that it's very hard to learn how to use the library from a reference manual only? What happened to tutorials and easy introductions to the usage of the library?
This has been a real problem for me. On more than one occasion I have found a library which could have been quite useful for me, but I have been completely daunted because the only documentation provided was a Doxygen-autogenerated reference manual, and nothing else. No matter how much I searched the home page of the library in question, not even a single tutorial, introduction or commented example program. Nothing.
Even worse, quite often (way too often) even those Doxygen-autogenerated reference manuals lack any kind of relevant comments or descriptions of many of the provided functions and types. They are more like pure listings of types and functions, with only little explaining text. That's approximately as unhelpful as it can get. I could get that exact same information by reading the header files directly.