Note: Some individual file downloads are hosted on an external site. I made them available for convenience and easier access in conjunction with this article. Other links go to the online manual on the doxygen homepage. (I guess I just created a lawyers nightmare.)

Doxygen is a free1) tool that extracts specific source code comments and analyzes the declarations of your code, to create a comprehensive online documentation, similar to the Tools/Build Comment web pages command in Visual Studio.NET. If you want the same for VC++6, or maybe some more flexibility and options, this article is for you.

Once setup, Doxygen can generate create a HTML documentation of your code at one click. It's still you who has to write the documentation, and if you want quality, it's still your job. However, an automated system can do a lot of vanilla tasks, and setting up the one-click documentation process is the first step to take: if you see the results of your effort immediately, it will soon feel natural to add the right type of comments.

This will show you how to integrate doxygen in VC++ 6, and set it up for one of your projects. I assume you already have a project you want to try doxygen on (if not, any C++ file will do). The whole process will take about 5 minutes (depends on your download speed).

Note: this setup does not work very well if you have a workspace with multiple projects in sub folders. See below for more.

/// Initializes the structure with an old an a new rectangle.
/// use this method if the window is about to be moved or resized (e.g. in
/// WM_SIZING or WM_MOVING handler)
void Init(RECT const & oldRect, RECT const & newRect, DWORD snapwidth)
{
// ...
}

I prepared an example for a small class of another article, which had virtually no documentable comments.

Note: as soon as you have added a basic doxy-comment to the important classes, you should turn off the EXTRACT_ALL option (as done in default2.doxygen). Undocumented classes are excluded, This will very much reduce the clutter in the detailed documentaiton section.

When working with VS.NET I noticed that the Tools/Build comment web pages is a great motivaiton for me to add useful function and class comments to my sources. Having a large VC6 code base to maintain, which, for a huge part, already has the comments, but no tool to extract, I was pointed to doxygen, and got it running in relatively short time. So, maybe you're not convinced, so here are three questions for you, with some (suggestive) answers.

First Question: Do You need a software documentation?

Reasons are many:

your company requires some documentation

you're not convinced you understand all of your code after not looking at it for half a year

your co-workers pester you with ""how do I do this" questions about your tool library.

you plan to retire or move on, and don't want your precious code to end up in the garbage, pillaged and rewritten by someone you don't even know, just because he doesn't take the time for it.

you feel better

Of course you can live without for an amazinghly long time, especially when you work on your own, or in a very small team. However, once a project grows beyond a certain size, you'll start to want some formal documentation. And the earlier you start, the better it is. Having set up a tool ready to be used, waiting for you tears down the biggest obstacle - getting started.

Second Question: Why use an automated system?

Documentation is up-to-dateYou are much more likely to change a comment atop of the function you fiddle with, than fire up MS Word, look for the function documentation, and change it there.

Reuse of your own commentsAssuming you already discovered the virtue of commenting your own code, the market value of your comments just doubled.

automatic formatting, and crosslinkingwith a few simple markups, you get documentation that looks professional and consistent, and creates links to the description of all important entities. Forget about struggling with MS Word.

In-code comments carry important meta informationNot all important information is available from the actual "raw" source code. Interface contracts, pre- and post-conditions, side effects, meaning of special parameters, etc. need to be known to anyone who is to maintain the code - be it yourself or someone else. A formal style for these comments, in conjucntion with a parser (like doxygen's XML export) can make this informaiton available in customized format for various recipients: be it project management, testers, and the like.

Third Question: Why doxygen?

It's free - so it's perfect for

cheapskates

sneaking it into the development process, in case noone cares about at your place

evaluating if and how an automated documentation system can help you

find out what features you expect when you shop for something better

OpenSource with installerIt's fairly comfortable to use (see also "Using Doxygen" below), so having the source code available comes as an added bonus.

ConfigurableWith a basic style sheet, and twiddling the options in the doxygen configuration file (easy by using the doxywizard), you can customize many aspects ofthe documentation to your needs.

Documenting an existing code base

Maybe you have a large project, where you wished someone would have had the patience to add extractable comments. Yet, the idea of walking through documenting 10.000 lines of code, and documenting them makes you shudder. Here are some suggestions:

Set up doxygen for the project. It's five minutes, and without nothing will happen

Document everything you write anew.

Touch up the code you work on. If you fiddle around with some function anyway, it's easiest to add some extra comments. Often it is just copying around / adjusting some existing comments to look a bit nicer.

Spend 5 minutes before lunch break on adding comments. Or: comment one function for each visit to the CodeProject lounge

Soon you will feel more "fluid" in documenting your code, and adding brief comments to an existing class is a matter of minutes. If the benefits of having the documentation kick in, you are encouraged to carry on.

The setup used above is quite generic. You can generate a default configuration file using doxygen -g, or by using the doxywizard. the latter makes playing around with various options fairly easy.

For each docmentable entity, doxygen looks for a brief comment, and a detailed description. The brief comment is addedto various overviews (liek the class member listing).

Comment Style

Doxygen recognizes other comment formats as well - I chose the above for both personal taste and compliance with those understood in .NET. For a comprehensive list, see Commenting the code in the doxygen documentation.

Other doxygen Options:

For the default.doxygen, I changed some of default options, notably:

EXTRACT_ALL enabled: so some generation is created even for "undocumented" codeI'd strongly recommend for existing projects to first add some documentation to the most important class declarations and methods, and then turn off the EXTRACT_ALL option. This makes the documentation less cluttered, and gives you even more more inducement to document what isn't

JAVADOC_AUTOBRIEF: this allows to have both the brief comment anddetailed description in one block (despite it's name, it works for C++ sources, too)The first line of a comment block (up to the first period) is used as brief description.

WARN_FORMAT set to $file($line): $text - so you can double-click doxygen warning messages in the output window to jump to the relevant source line

INPUT : I added a single "." as INPUT directory, and checked the RECURSIVE option. this will scan the working directory (set to the workspace folder in the VC++ custom tool), and added a reasonable list of files to scan (.IDL files work very well, too!). You could specify exclude patterns, too (e.g. *_i.c and *_p.c for ATL projects to exclude some of the internal guts from documentation)

Source browser: I enabled the SOURCE_BROWSER option, so the sources are included and crosslinked (doxygen removes all doxygen-style comments, but leaves all other comments in).

I disabled the REFERENCED_BY_RELATION and REFERENCES_RELATION options. They can be valuable if you want to explore the interdependencies of complex code, but for the things I'm working on it's just clutter.

for the HTML_OUTPUT I set doxydoc as directory (it will be created under the working directory)Tip: When specifying dorectory names in doxygen config files -

if it contains spaces, put it into quotes (this is a good idea for other options as well)

do not end them with a backslash - doxygen uses it to spread argument lists over multiple lines

GENERATE_TREEVIEW : While I left it disabled for the default, you shoud try it!

Documentation Markup:

Doxygen allows for simple markup tags in the comments (I used some in the sample documentation) they start with either a backslash, or an @. The most important I listed here:

\param name descripiton

Intended for documenting function parameters. see the full sample source and documentation for how it looks like.

\return description

desribe what a function returns

\b \c \e

set the next word to bold, italic, or courier, respectively. e.g./// You can make things \b bold, \e italic, or set them in \c courier results inYou can make things bold, italic, or set them in courier.

\code \endcode

starts and ends a section of code, respectively. (it will be formatted nicely)

\n

force a newline

\internal

starts a paragraph with "internal information" (such as implementaiton details). The paragraph will be included only if the INTERNAL_DOCS option is enabled.

\mainpage

Indictaes that the following section should appear on the main page. it's a good place to introduce your most important classes, etc. (entities will be crosslinked)

\par\par Title

Starts a new paragraph (optionally with a paragraph title), works also inside other paragraphs (such as \param)

Lists

Doxygen automatically creates a list if multiple lines start with a dash at the same position. Numbered lists can be created by starting the line with a dach and a hash (-#). See the doxygen documentation for more.

Doxygen supports many more tags, many of them allowing for further markup, or are intended for working in conjucntion with the XML export. (e.g. you can makr the specificaiton of pre- and post-conditions, bugs, test cases, todo's, etc.)

In closing, just a little tip: Together with doxygen comes DoxyWizard, a UI tool to edit the configuration files. It's ok to use, the "quick help" gives a short explanaiton of each option. As I named all my config files .doxygen, I associated this extension with doxywizard, so life got much easier, and playing around with the options is much more fun.

Other Systems:

If you have experience with other documentation systems, feel free to (dis-)recommend them in the comments section - as long as you don't make it an advertisement, and stay within what's considered good taste on CP.

Share

About the Author

Peter is tired of being called "Mr. Chen", even so certain individuals insist on it. No, he's not chinese.

Peter has seen lots of boxes you youngsters wouldn't even accept as calculators. He is proud of having visited the insides of a 16 Bit Machine.

In his spare time he ponders new ways of turning groceries into biohazards, or tries to coax South American officials to add some stamps to his passport.

Beyond these trivialities Peter works for Klippel[^], a small german company that wants to make mankind happier by selling them novel loudspeaker measurement equipment.

Where are you from?[^]Please, if you are using one of my articles for anything, just leave me a comment. Seeing that this stuff is actually useful to someone is what keeps me posting and updating them.Should you happen to not like it, tell me, too

Comments and Discussions

Thanks for your article about doxygen. I started with version 1.5.6 in 2008 with VC++6 professional and I'm using now version 1.8.2 as tool in visual studio 2010. I have installed doxygen, grapviz, fart and html help workshop. In the external tools I call a cmd-file to create submaps in my project add add the doxygen-file, mainpage-file and project-logo. Fart replaces default text with the TargetName in both files. It goes to far to show all the details, but setup the documentation for a new project is done in just two mouse clicks!