RFC-225 reminded me that we still haven’t come up with a fix for the single biggest problem (IMO) with our C++ documentation system: the huge number of Doxygen warnings that are due to Doxygen parsing failures rather than actual problems in our markup. This makes problems in the markup a lot harder to spot, of course, allowing those to proliferate as developers give up on warning-free builds.
Most of these come from Doxygen’s failure to reliably match function definitions in .cc files with their declarations in .h files, especially when templates and/or namespace aliases are involved. The easiest fix for that is to just disable Doxygen parsing of .cc files, at least once the Doxygen comments have been moved to .h files (where they should be for all new code). But that also prevents the .cc files from being included in the Doxygen outputs. I’m not personally convinced we should be including header files (let alone .cc files) in Doxygen; that’s the third place I’d go to look for source code (after my local copies and the GitHub web interface), but I do agree that having links from the reference documentation to the code where they’re defined is useful.
So, where do we go from here?
-
Does anyone have enough experience with Doxygen to have any ideas on how we could fix this sort of problem by configuring it better? I couldn’t even figure out how to turn off warnings about this particular problem, but that was a long time ago, and Doxygen made have gotten better at this.
-
Now that we’re using GitHub much more, is having the .cc files in the Doxygen outputs still useful? How many people are currently using Doxygen HTML to look at source code?