Doxygen – painfree documentation using comments

Leaving google mocks aside for the moment,  I realised that not only did I needed coverage reports, but I also should start to document my code a bit better so I could automate creation of the documentation at a later date.

Having used doxygen several times in the past, this was an obvious choice and just needed a few things setting up. Firstly install the thing:- apt-get install doxygen and an old but stable version is ready in a minute or two. (It took a while to install because of the latex and rtf dependencies needed installing too)

Then I needed a config file doxygen -g Doxyfile inside the root of my code tree is enough to get a boilerplate. I customised the Doxyfile a bit to just create html reports and some specifics for C/C++ but generally its as it comes and is very straightforward to edit. Of course if you install the Doxygen Gui it will do it all for you.

Then the moment of truth, run the doxygen command and a few seconds later I have fully documented code.


So next step was to install a plugin for vim to make adding Doxygen comments easier. DoxygenToolkit.vim was just the ticket and I went through each class/function/variable adding Dox comment blocks, giving each file a DoxLicence and  DoxAuthor too.


A re-run of doxygen and it’s starting to take shape.

  • I had to go back and modify my TODO: labels to \todo so they would be found easier.
  • I had to add @fn to the comment blocks for the unit tests, as it doesn’t understand they are macro expansions.

Then it started to look great and gives me a way of instantly producing the documentation when I want.

I didn’t push the ending html up to the git repo as I can always check out a specific revision and recreate it at that point anyway. So no point tying up the repo with extra files to track.

Spencer Westwood

Author, musician, developer and generally a bit of a self confessed computer geek.