2016-06-26

Doxygen error parsing in Eclipse CDT

Eclipse (or is it the CDT?) has, by default, some Doxygen integration: if the preferences are set appropriately, Doxygen-style comments are highlighted differently, and Doxygen commands in those comments are further highlighted.

But that's about it. A particular missing feature is that errors in the comments are not highlighted in any way; and that's what made me look for a better alternative.


There is the Eclox plugin for Eclipse, but it is almost useless: all it does is run Doxygen on configurable Doxyfiles, and offer a button to do so from the toolbar. One can do the same in a variety of ways in the naked Eclipse/CDT. [1]

And turns out that one of these ways not only allow you to launch the Doxygen building of docs, but will detect and highlight the Doxygen-reported warnings and problems!

How to do it? Just add a C/C++ build configuration which, instead of running make, will run your Doxygen executable, in the expected work directory, with "build target" the appropriate Doxyfile. When you run this build (which can be done from the toolbar), the Doxygen output will go to the build console, and so will get analyzed by the CDT error parsers.

...and at this point I thought that I would have to configure my own Doxygen error parser, but no! Turns out that the Doxygen warnings are similar enough to gcc or make warnings that the normal parsers will already detect them. So, you're finished!

Note that I'm doing this in a CDT "Makefile project with existing code" project, which gives you more configuration freedom than other kinds of projects. YMMV.

Also, I mentioned that there are other ways to launch Doxygen builds without Eclox. They might have some advantages, though they didn't work for me. They are:
  •  add a Make Target, in which you can configure the executable and target (read: arguments to the executable) to be run. The output again goes to the build console, so it is parsed by Eclipse, so this should be OK. However: in my project I needed to also configure the working directory for the executable, and that option is not configurable for Make Targets. [2]
  • configure an External Tool. This is just a convenience to run a random executable and have it's input/output console inside the IDE; as far as I can tell, there is no way to make Eclipse parse that output console, so this is of little use.
  • add a new Builder in the project preferences, and configure it to launch Doxygen. The Builder can be configured to run after the normal builder on an auto-build, or on a manually-triggered build. However, the Builder is just another External Tool that gets run automatically. So again this is of little use.

[1] Eclox also offers an editor for the Doxyfile. In my opinion and experience, it's unnecessary, and probably outdated, since Eclox has been unmaintained for years.

[2] Furthermore, just for organization purposes: I don't know what is the connection between this kind of Make Target and a Build configuration as mentioned earlier. Maybe Make Targets are intended to be used when Eclipse is generating the makefile, which is not my case. So for the case of the "Makefile project with existing sources", the Build configuration is a more natural way - you probably already have some other build configs, like Debug or Production, right?

No comments

Post a Comment