IT PRO: Blogs: Dave F: Programmers Documentation

Home

Dave F's Blog

Programmers Documentation - the doxygen way

Posted in Open Source Software, QT, Coding on September 16, 2008 at 11:03 am

I have been producing some programmers documentation. The shrieks of horror (or snores of boredom) that normally accompany such a statement have been mercifully short. I have been using doxygen http://www.stack.nl/~dimitri/doxygen/ (more info at http://en.wikipedia.org/wiki/Doxygen). It took a bit of fiddling to get it set up (and it needs a bit more, I seem to have to hard code the directories rather than go relative from the working dir - any help always appreciated!) but seems OK now.

Things I’d recommend are enabling the pre-processor, disabling all output except HTML (until you have a good set up - you may want some other output at the end). If you’re using QT add moc_*.* to the exclusion list. If you’re using SVN excluding the svn dirs is a good idea (I think I did this but I can’t remember how!), don’t hide undocumented classes / methods, add links to the actual code (source browser) and use the built in class diagram generator. Some of this you can do from the wizard. The excludes & the pre-processor I did from expert mode, I also set the “strip from path”, turned on all the extract all / private/ static / local turned off strip code comments, requested an alphabetical index (you can’t have too much info can you?). A nose around the human readable config file is also a good idea just to give you a better idea of what can be done. Whether you choose plain HTML or frames is up to you, frames look better but my ie is set to disable active content so it is not so good to use.

Anyway, there is a certain satisfaction in generating stuff you can click on and see diagrams in without having to type it all in. The whole process is much more like the program / build / test sequence that developers are used to than the boring old type it & proof read it methods of old.