Writing documentation is quite a chore. What other explanation could there be for the fact that some organizations have one or perhaps several people for whom documentation writing is their entire job description. One day, a Java developer asked, “What if we created a tool that could generate documentation from our source comments?” and JavaDoc was born. Now C# developers have something equivalent with XML comments as well. What about C++ programmers though? Are they doomed to creating documentation the old fashioned way? Not if they take a good deep breath of Doxygen.
Doxygen is a command line, open source documentation-generator suitable for use with C-style languages like C++, C, IDL, Java, and even C# or PHP. Aside from being open and nonproprietary, Doxygen distinguishes itself from vendor alternatives like JavaDoc by building in support for a wider range of document formats. In addition to HTML, documentation can be created in LATEX, PDF, RTF, PostScript, compressed HTML (Microsoft HTML Help compatible), and even *NIX man page formats. Doxygen is even flexible enough to create user-level documentation files: The Doxygen user manual was created by, as the tool’s creator puts it, “abusing” it. Doxygen even includes a built-in C Macro preprocessor.
Flexible and powerful
When browsing the included user manual for the first time, Doxygen can appear frightfully complicated. But this isn’t necessarily so—you can make things as complicated or as simple as you want them. Doxygen is surprisingly flexible.
To create simple documentation, you just need to know about a few special comment styles, some of which will look familiar to you if you’ve ever used JavaDoc. As your needs become more advanced, you can take advantage of special formatting capabilities to include specially formatted lists or diagrams in your documentation, or even link in blocks of source code. The latter is useful for peer reviews or when you’re interested in documenting the internal structure of an application.
Doxygen makes use of a text-based configuration file, in which you can set a large set of options to control Doxygen’s behavior. There’s support for file and directory pattern matching to control which source files Doxygen examines, and recursive directory scanning that's configurable through this file. Since Doxygen accepts the name of its configuration file as a command line argument, it’s possible, and preferable, to maintain multiple configurations for multiple projects. If you dislike editing text files by hand, the included Doxywizard utility presents a GUI-based way to modify the configuration file.
Building documentation the Doxygen way
The best way to get started with Doxygen is to use the –g command line switch to have the tool generate a configuration file template for you. Or you can use the Doxywizard application instead of trying to make one by hand. There are a large number of options you can set in the file, and it’s easy to get overwhelmed. Explanations for all the available options can be found in the comprehensive manual.
By default, Doxygen ignores regular comments, although you can force it to include regular comments via a configuration file item. Doxygen makes use of two special comment types: brief and detailed. Brief comments are just that, brief, one-line descriptions of a code structure, and are indicated by including an extra forward slash, or an exclamation point in a C-style single line comment like so:
/// This is a brief comment
//! This is also a brief comment
Detailed comments, on the other hand, can span multiple lines, and are meant for more in-depth comments. These are created by adding an exclamation point to a multiline comment indicator like this:
This is a detailed comment
The JavaDoc multi-line format (/** … */) can be used as well. These two different comment styles appear in different places in the generated documentation. There’s an excellent example of a documentation page created from a simple C++ program in the online user manual, so I won’t repeat it here. If you need more complexity, Doxygen is capable of advanced formatting like groups and lists, although it’s possible to create perfectly serviceable docs using just these two basic comment types.
Doxygen’s capabilities don’t end with just simple comment extraction, though. Doxygen can also create color-coded inheritance diagrams from source files. These diagrams can be made rather complex by using a third-party documentation tool called dot. This capability makes Doxygen particularly useful for reverse engineering existing source and helping you get your head around someone else’s undocumented source—a sadly common state of affairs. Once again, check the online user manual for an example of the sorts of diagrams Doxygen can create.
Doxygen brings advanced documentation generation abilities of the kind offered by JavaDoc to the world of C++ and C# developers. Being able to include source code blocks and normal comments along with the ability to easily generate documentation in multiple formats brings welcome flexibility to a tool that’s simple to use, yet very powerful.