Posts tagged ‘java’

February 9th, 2009

Doxygen

So I’ve been playing around a little with Doxygen. If you don’t already know, Doxygen is tool for generating documentation from source code, similar to Javadoc in the Java world but a lot more powerful. It has support for generating documenation for a selection of programming languages including C, C++, Python, PHP, Java amoung others. Documentation is generated in HTML format by default but there are options for producing PDF’s, man pages, RTFs, CHMs and more.

The documentation is extracted from source files, using special comment blocks. Doxygen is able to filter out what is ment to be documentation and not just code comments. Since the documentation is in-lined with the source code there is a higher chance of the source and documentation staying consistent, if they are separated chances are that the documentation will become stale as the source code is changed but not reflected in the documentation.

I installed the Doxygen package on Windows and it comes with a handy GUI wizard for creating a configuration file and for running the Doxygen. There are lots of options available for working with Doxygen and the wizard makes it easier to get started, it also gives context sensitive information for each option so you know what each option is for.

When documenating your source code there are a few options for marking the documentation using special documentation blocks which are basically comment blocks. Doxygen supports the Javadoc style:

/**
 *  Documentation here
 */

As well as the Qt style:

/*!
  Documentation here
 */

Which style you choose is a matter of preference, personally I prefer the Javadoc style mainly because I’m used to it and have been using it with Java and PHP for a while so for this project I will continue using the Javadoc style to document my C++ source code.

By default Doxygen is able to generate simple diagrams that show inheritance for C++ classes but if you install a third-party package called Graphviz then Doxygen is able to take advantage of that and produce much more complicated and informative graphs and diagrams, including UML class diagrams.

Even on source code that has no documentation blocks, Doxygen is able to generate basic documentation of the code structure which is very useful when trying to understand a large source code distribution, couple this with the Graphviz generated diagrams it becomes very easy to visualize the code.

The diagram below was generated by Doxygen from Moge’s source code. It shows two of Moge’s classes GameEngine and Window, and shows the relationship between them, i.e. dependency, it also shows dependency on C++ Standard classes.

GameEngine class diagram