# Doxygen parsing of .cc files **URL:** \ **Category:** Data Management\ **Tags:** doc-engineering\ **Created:** [September 19, 2016, 3:50pm UTC](https://www.rubin.community/t/doxygen-parsing-of-cc-files/1175 "2016-09-19T15:50:07Z")\ **Posts on this page:** 8\ **Page:** 1
**Author:** ![jbosch](https://sea2.discourse-cdn.com/flex002/user_avatar/www.rubin.community/jbosch/32/12_2.png) [@jbosch](https://www.rubin.community/u/jbosch)\ **Post date:** [September 19, 2016, 3:50pm UTC](https://www.rubin.community/t/doxygen-parsing-of-cc-files/1175/1 "2016-09-19T15:50:07Z")
[RFC-225](https://jira.lsstcorp.org/browse/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? ---
**Author:** ![timj](https://sea2.discourse-cdn.com/flex002/user_avatar/www.rubin.community/timj/32/10_2.png) [@timj](https://www.rubin.community/u/timj)\ **Post date:** [September 19, 2016, 3:59pm UTC](https://www.rubin.community/t/doxygen-parsing-of-cc-files/1175/2 "2016-09-19T15:59:17Z")
> [@jbosch](#): > > 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. There is an open ticket for updating `doxygen` ([DM-4891](https://jira.lsstcorp.org/browse/DM-4891)) but it’s blocked because of a cmake version issue on CentOS7 and I haven’t spent any time working out whether that’s a hard version requirement or a soft one. ---
**Author:** ![RHL](https://sea2.discourse-cdn.com/flex002/user_avatar/www.rubin.community/rhl/32/25_2.png) [@RHL](https://www.rubin.community/u/RHL)\ **Post date:** [September 19, 2016, 4:02pm UTC](https://www.rubin.community/t/doxygen-parsing-of-cc-files/1175/3 "2016-09-19T16:02:56Z")
Do we know that this fixes the problem? I checked wth Jeff a year or two ago, and we could send some money to Dimitri the Doxygen to get the bugs fixed. This is orthogonal to the which-files-do-we-doxygenate, but still worth thinking about IMHO. ---
**Author:** ![timj](https://sea2.discourse-cdn.com/flex002/user_avatar/www.rubin.community/timj/32/10_2.png) [@timj](https://www.rubin.community/u/timj)\ **Post date:** [September 19, 2016, 4:04pm UTC](https://www.rubin.community/t/doxygen-parsing-of-cc-files/1175/4 "2016-09-19T16:04:21Z")
> [@RHL](#): > > Do we know that this fixes the problem? No idea, but it seems a trivial thing to try and you can just build `doxygen` using that ticket branch and see what happens if you have a reasonably modern `cmake`. ---
**Author:** ![jsick](https://sea2.discourse-cdn.com/flex002/user_avatar/www.rubin.community/jsick/32/672_2.png) [@jsick](https://www.rubin.community/u/jsick)\ **Post date:** [September 19, 2016, 4:28pm UTC](https://www.rubin.community/t/doxygen-parsing-of-cc-files/1175/5 "2016-09-19T16:28:11Z")
> [@jbosch](#): > > 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). How much work would it take to move all Doxygen comments from `.cc` to `.h` files? It’d be nice to add this to RFC-225’s standards update and maybe do this at a meeting hack week at the same time as we’re also updating Python docstrings. cc: @KSK @swinbank > [@jbosch](#): > > 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? My plan is to _not_ have source code inlined with the API reference. Instead, my plan is to link to GitHub’s source pages (linked for that branch/tag). Same for Python API references. * * * Separately, @timj pointed out to me that a lot of doxygen warnings happen in the per-package doxygen builds from links to APIs that exist in other API packages. This may be a problem for me since I plan to harvest Doxygen’s XML output from per-package builds for the overall Sphinx documentation build. ---
**Author:** ![jbosch](https://sea2.discourse-cdn.com/flex002/user_avatar/www.rubin.community/jbosch/32/12_2.png) [@jbosch](https://www.rubin.community/u/jbosch)\ **Post date:** [September 19, 2016, 4:51pm UTC](https://www.rubin.community/t/doxygen-parsing-of-cc-files/1175/6 "2016-09-19T16:51:56Z")
> [@jsick](#): > > How much work would it take to move all Doxygen comments from .cc to .h files? It’d be nice to add this to RFC-225’s standards update and maybe do this at a meeting hack week at the same time as we’re also updating Python docstrings. There are a lot of older classes in afw and meas\_algorithms that still have Doxygen markup in the .cc files, but I bet the transition could still be done by a single person in a week. > [@jsick](#): > > My plan is to not have source code inlined with the API reference. Instead, my plan is to link to GitHub’s source pages (linked for that branch/tag). Same for Python API references. This sounds excellent, and I imagine it’d be quite doable with probably just some regex parsing of the Doxygen XML, but I think you’d still have to make use of Doxygen parsing those source files in order to know where a particular class or function is declared and defined if you wanted to link to it at that level of granularity. > [@jsick](#): > > Separately, @timj pointed out to me that a lot of doxygen warnings happen in the per-package doxygen builds from links to APIs that exist in other API packages. This may be a problem for me since I plan to harvest Doxygen’s XML output from per-package builds for the overall Sphinx documentation build. As long as the references obey the eups dependency ordering (packages can refer to packages they depend on, but not packages that depend on them), these _should_ be handled by Doxygen’s “tag” mechanism. That doesn’t always work as well as it should, though, and I don’t know if that’s an intrinsic limitation or because we’re doing something wrong. And you’re right that it will never correctly handle references that don’t obey the eups dependency ordering. ---
**Author:** ![timj](https://sea2.discourse-cdn.com/flex002/user_avatar/www.rubin.community/timj/32/10_2.png) [@timj](https://www.rubin.community/u/timj)\ **Post date:** [September 19, 2016, 5:01pm UTC](https://www.rubin.community/t/doxygen-parsing-of-cc-files/1175/7 "2016-09-19T17:01:26Z")
> [@timj](#): > > updating doxygen Here is the changelog: [http://www.stack.nl/~dimitri/doxygen/manual/changelog.html](http://www.stack.nl/~dimitri/doxygen/manual/changelog.html) Lots of changes in 3 years. ---
**Author:** ![FernOfGitHub](https://avatars.discourse-cdn.com/v4/letter/f/0ea827/32.png) [@FernOfGitHub](https://www.rubin.community/u/FernOfGitHub)\ **Post date:** [September 19, 2016, 11:42pm UTC](https://www.rubin.community/t/doxygen-parsing-of-cc-files/1175/8 "2016-09-19T23:42:06Z")
Hello. First time contributing to LLST forum. llvm, along with clang, use /// for all their Doxygen comments. The template declarations are recognized without \tparam For example, [http://llvm.org/docs/doxygen/html/classllvm\_1\_1IntrusiveRefCntPtr.html](http://llvm.org/docs/doxygen/html/classllvm_1_1IntrusiveRefCntPtr.html) This stackoverflow discussion talks about c++ and templates. A small change in syntax seems to correct errors. > Posted about a year ago. Change /\*! to /\*\* and \param to \tparam