# 10 Minutes to document your code

By , 19 Jan 2003

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.)

## Welcome!

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.

1) Doxygen is written by Dimitri van Heesch, and released under the GNU public license (GPL). The documentation created by doxygen is not affected by the GPL. See the Doxygen Homepage for more information.

What do I have for you today?

1. Setting it up - a quick step-by-step guide to setting up and integrating doxygen with VC++ 6
3. Rationale - why to use doxygen? (skip if you are already convinced)
4. Working with Doxygen - discusses the sample setup from 1), and provides an introduction to the most important doxygen features.
5. Additional Resources (not much right now)

So let's jump right in!

## Setting it up

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.

 doxygen binaries [^] 1. Download the Win32 binaries and install them I'll assume in the following you installed doxygen in c:\program files\doxygen. doxygen tools 2. Download and extract my doxygen tools and keep them safe and warm in a folder of your choice. They contain all the individual files mentioned in this article Add VC++ Tool:"doxygen" Add a new custom tool, called "DoxyGen", with the following parameters: Command: c:\program files\doxygen\bin\doxygen.exe (or where you installed it) Arguments: "$(WkspDir)\default.doxygen" (the config file - include the quotes!) Initial Directory: "$(WkspDir)" Check the "Use output directory" box Add VC++ Tool:"view results" add another tool, to view the results new "View DoxyDoc" tool, to view the results: Command your favorite browser, e.g. c:\program files\internet explorer\iexplore.exe Arguments: "$(WkspDir)\doxydoc\index.html" Initial Directory: leave empty Add to project open the project you want to add the file to copy the default.doxygen file into your project folder (this file contains doxygen configuration options) open it for editing in VC++ change the ***PROJECT NAME*** to the name of your project right click the file, and choose "Insert File into Project / ". If you use VSS, I'd also add it to SourceSafe You're done! Try! choose Tools/doxygen from the menu, and watch the magic happen (doxygen will log it's progress and complaints to the output window).Choose Tools/View results to explore the documentation. The "Main Page" is probably rather boring. Click on "Data Structures" in the top line to browse your classes etc. ## Documenting Basics Unless you already use some comment style that doxygen understands, the documentation is pretty much meaningless. So what can you do? 1. Add a comment block before classes and structures, using /// Just use /// for the comment block: /// SNAPINFO holds the data for calculating a modified window rect. Since it /// only works on coordinate rects, it can be used without any actual Windows. struct SNAPINFO { // ... } 2. Add a brief comment to to class member declarations Use /// if you put a single line before the member. Use ///< if you put the comment behind the member struct SNAPINFO { /// Init, using a pre-change and a post-change rectangle void Init(RECT const & oldRect, RECT const & newRect, DWORD snapwidth); void SnapHLine(int y); ///< Snap to a horizontal line } 3. Add a detailed description to the method implementation as with classes, use a /// - comment block /// 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.  original code [^] documentation [^] brief comments added [^] documentation [^] 13 new lines 2 with comment style modified method desciptions added [^] documentation [^] 14 additional lines (with ehavy copy&paste) without EXTRACT_ALL option documentation [^] 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. ## Rationale 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-date You 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 comments Assuming you already discovered the virtue of commenting your own code, the market value of your comments just doubled. • automatic formatting, and crosslinking with 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 information Not 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 installer It's fairly comfortable to use (see also "Using Doxygen" below), so having the source code available comes as an added bonus. • Configurable With 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. ## Working with Doxygen 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" code I'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
• doxygen will try to create non-existing output directories, but cannot generate multiple levels.
• 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. More...(doxygen documentation) 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.) HTML(doxygen documentation) Doxygen also supports HTML tags, which get converted to other outputs mroe or less correctly.

Macros:

It's convenient to set up some auto-text bound to hotkeys for writing documentation. I just use some macros, and assign shortcuts to it manually: Setup is a bit of a hassle, but it's worth it:

• copy doxygen.dsm into the [DevStudo]\Common\MSDev98\Macros folder
• Start VC++, choose Tools/Customize...
• on the "Add ins and macros" tab, enable the doxygen.dsm macro file
• On the Keyboard tab, choose "Macros" under Category, and assign your preferred shortcuts to the commands

Here's a list of the macros I use:

 Macro Name Description my shortcut DoxyComment three slashes and a space (I use it rarely , but it's there) Ctrl-# (german keyboard..) DoxyCommentNL newline + '/// ' - perfect for writing block comments (just press Ctrl-Enter instead of just Enter) Ctrl-Enter DoxyCommentPrev '///< ' : for brief comments behind the declaration Ctrl-Shift-# DoxyDocFunction a simple header to comment a function Ctrl-Shift-F

Style Sheets:

You can generate a default doxygen style sheet, HTML header and footer by calling

doxygen -w html <header_name> <footer_name> <stylesheet_name>

The default style sheet is a good starting point for your own.

DoxyWizard:

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.

Enjoy! And document well.

 peterchen Klippel Germany Member
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

Votes of 3 or less require a comment

 Search this forum Profile popups    Spacing RelaxedCompactTight   Noise Very HighHighMediumLowVery Low   Layout Open AllThread ViewNo JavascriptPreview   Per page 102550
 Detecting circular references borgman 12 Aug '08 - 10:14
 option WARN_FORMAT Theo Buys 7 Aug '08 - 1:38
 Thanks for your brief tutorial of doxygen. I notice that your default.doxygen file is for the 1.3-rc version. When generatating a new default.doxygen I overlooked the option WARN_FORMAT which becomes "$file:$line: $text". To make the warning clickable in the output window to open the source, change it to "$file($line):$text" like you did. Sign In·View Thread·Permalink
 Thanks coder112 26 Apr '08 - 19:09
 This tutorial was what got me to actually try and use Doxygen because it convinced me it would be worth the effort invested to make it go. Sign In·View Thread·Permalink
 HH_GET_WIN_TYPE error. JediScientist 20 Dec '07 - 10:14
 I compile my chm files fine on Windows, except when I move the *.chm file to another location I get the following: "The window name "main" passed to HH_GET_WIN_TYPE has not been specified." Why does this happen? Sign In·View Thread·Permalink
 Re: HH_GET_WIN_TYPE error. JediScientist 27 Dec '07 - 11:23
 Double-clicking warning messages in VC7 flipdaddyyawnman 19 Apr '07 - 9:14
 It took me a little while, but I finally got the doxygen warning messages to show up in the "Task List" in VS.NET 2003 so I could double-click them (I could double-click them in the "Output" pane, but it's nicer to be able to do it from the task list along with all the compilation errors and warnings ).   I set WARN_FORMAT to "$file($line) : warning : $text". The quotes are needed, because you lose the spaces without them, which causes VS.NET to ignore the messages. Here's what I had in my doxyfile: WARN_FORMAT = "$file($line) : warning :$text"   We've found doxygen very useful at my job -- I also like the ability to generate PDF's (if you install Ghostscript and a LaTeX distribution and maybe GraphViz).   Phillip Sign In·View Thread·Permalink
 Re: Double-clicking warning messages in VC7 mickey35 17 Sep '07 - 1:00
 Re: Double-clicking warning messages in VC7 flipdaddyyawnman 17 Sep '07 - 3:10
 Re: Double-clicking warning messages in VC7 mickey35 17 Sep '07 - 3:20
 Re: Double-clicking warning messages in VC7 flipdaddyyawnman 19 Oct '07 - 2:54
 DOxygen and VC 7 jjcambefort 5 Dec '06 - 21:53
 Hello, I dont' succeed working in VC7.   For doxygen I set the arguments as $(ProjectDir)\default.doxygen (without quotes) and inititial directory as$(ProjectDir) sometimes it works, sometimes it freezes   For view with IE7 I always got an url like file://%22//C:\projets\essai\doxydoc\index.html witch obviously doesnt' work   If someone could help, thanks !   regards JJC Sign In·View Thread·Permalink
 Borland Builder 6 rvanpassel 23 Oct '06 - 2:04
 The Wizard runs well. (it generates html output) I Couldn't quite get it to work with Borland Builder 6, though. (No, I did not mean Builder 2006) Any Ideas?   The Graphical Diagrams do not seem to work?   Thanx for this 1 minute guide, though. It helped a lot...   paper, not paper Sign In·View Thread·Permalink
 Re: Borland Builder 6 peterchen 23 Oct '06 - 7:52
 Re: Borland Builder 6 rvanpassel 23 Oct '06 - 13:51
 Inserted MFC code Friedhelm Schuetz 5 Sep '06 - 4:07
 Re: Inserted MFC code peterchen 7 Sep '06 - 8:01
 defining functions question. chris175 31 May '06 - 5:08
 Say you have a function that you want to document in the class but isnt coded in the class definition. For example...I am using MSChart and which is a class created from the Visual Studios C++ 6.0 and it has a bunch of functions. It is missing the event functions and I would like to document them with DOxygen. How do I accomplish this?   Chris Sign In·View Thread·Permalink
 Re: defining functions question. peterchen 31 May '06 - 10:55
 Re: defining functions question. chris175 1 Jun '06 - 0:58
 how to understand list of elements and show on diagram meouvn 17 Mar '06 - 1:21
 I have a code here, i want doxygen understand PSmileys have list of Smiley and show on diagram as Collaboration diagram or Inheritance diagram /** * @class PSmileys * @brief * List of smileys. * * @author Duy Trinh * @version 1.0.1 * @date 17 Feb 2006 */ class PSmileys { public: // Define Child classes /** * @class PSmiley * @brief * Smiley. * * @author Duy Trinh * @version 1.0.1 * @date 17 Feb 2006 */ class PSmiley { public: /** * A constructor */ PSmiley(); /** * A destructor. */ virtual ~PSmiley(); private:   };   public: /** * A constructor */ PSmileys(); /** * A destructor. */ virtual ~PSmileys(); private: CArray m_cSmileyList; };   -------------------------- ERP VN: www.erpvn.net Sign In·View Thread·Permalink
 Re: how to understand list of elements and show on diagram Mihai Moga 20 Mar '06 - 22:06
 Re: how to understand list of elements and show on diagram meouvn 21 Mar '06 - 15:00
 Updating changes to files Anand123M 13 Jan '06 - 1:34
 Hi, Nice article to get started !!! I just wanted to clarify a doubt... Suppose I have 100s of files within my project and I change only the signature of one of the functions in a class, is there any way that doxygen can update the documentation for only this class/file or should I run doxygen for the whole project?   Thanks   Anand Sign In·View Thread·Permalink
 Re: Updating changes to files peterchen 13 Jan '06 - 22:40
 Are their any document things for c++ that use c# style comments? FocusedWolf 6 Jan '06 - 8:35
 class __declspec(dllexport) Bob Flynn 25 Oct '05 - 14:58
 Thanks or this great article, you have made using Doxygen straight forward and easy.   While trying this out I noticed I as missing some classes. Doxygen does not seem to handle class __declspec(dllexport) CClassName.   Have you been able to determne a fix for this? Sign In·View Thread·Permalink
 Re: class __declspec(dllexport) Bob Flynn 26 Oct '05 - 2:24
 VC6 bug?? doxygen bug? giusai 3 Oct '05 - 2:32
 Hi, I tried all steps to configure my vc++ tool menu and everything works fine! The problem verifies when I try to process a workspace that is stored under C:\Documents and Settings\etc..... And i observe this both to generate the document (doxygen.exe) and to view it (iexplore.exe)...   For processing phase i get the message   The error message is: Error: configuration file C:\Documents not found! Tool returned code: 1   For the exploring phase i get an error from Explorer.   It seems it's not able to understand C:\Documents and Settings. It tries to look in C:\Documents%20and%20Settings\....   What's matter?? thanks giusi Sign In·View Thread·Permalink
 Re: VC6 bug?? doxygen bug? peterchen 3 Oct '05 - 2:45
 Re: VC6 bug?? doxygen bug? giusai 3 Oct '05 - 3:02
 Really nice jensus kapsylus 4 Sep '05 - 10:52
 I'm by no means a professional programmer, but the project I'm working at the moment has grown somewhat fat, so I installed Doxygen and gave it a try. And it works really good! It's a kick to see all those classes nicely together, with all the colours and stuff... Sign In·View Thread·Permalink
 Neat source documentation site Anonymous 17 Aug '05 - 14:06
 Re: Neat source documentation site Herbert Sauro 21 May '07 - 7:09
 doxygen and visual studio 2005 beta 2 roerich 11 Aug '05 - 23:23
 Hi,   I just have adapted your tutorial to VS 2005 beta 2.   Instead of $(WkspDir) use$(ProjectDir) when you construct the DoxyGen command in the External Tools menu. This is because you can say that all projects of a solution shall be created in their own subfolder and those folders are in parallel to the solution file (.sln).   In the View DoxyDoc command I adapted the Arguments line to $(ProjectDir)doxydoc/index.html since$(ProjectDir) contains a backslash at the end and iexplore.exe cannot find a document called \$(ProjectDir)\doxydoc\index.html Sign In·View Thread·Permalink
 Problem viewing the code of .cpp/.h files thevoyager 6 Jul '05 - 19:12
 Hi, I tried Doxygen after reading this article and found it amazing. I got all the things right except the source code of the files. It just shows a blank box on the page. In the source of the html page, there is a tag
. If I make it
, it shows the page correctly. Can somebody please explain what this tag is and is there any other "decent" way than going to the source of every page and modifying this tag.  Regards,Pravin
 Re: Problem viewing the code of .cpp/.h files peterchen 7 Jul '05 - 11:42
 Doxygen and C Files Roadrunner101 21 Jun '05 - 4:02
 Hallo,   i hope anone can help me with doxygen. I want to crate a documantation of several c programms with doxygen and i want to have a first big general programm description created by doxygen. The problem is that every kind of comment must be related to a function, class, variable and so on. And I don't want to add a dummy function or something like this.   Thanks for help?   Greets   Roadrunner Sign In·View Thread·Permalink
 Re: Doxygen and C Files peterchen 21 Jun '05 - 5:34
 HTMLHelp - chm Nick_David 19 Jun '05 - 23:05
 Did someone generate CHM from doxygen docs? This feature would be very usefull. Contents, Searching, Keyword index and MSDN integration. That would be really cool and convinient.   Best regards Nick Sign In·View Thread·Permalink
 Re: HTMLHelp - chm peterchen 21 Jun '05 - 5:45
 Re: HTMLHelp - chm Nick_David 21 Jun '05 - 11:20
 Good article CasualT 10 Jun '05 - 11:59
 I got the Doxygen tool setup fine and I can view my documentation and I'm ahppy with that. But when I tried to setup the tool for viewing the HTML, IE can't find it. The URL it is using looks correct but it claims it can't find anything: "http://%22c/Directory/Subdir/html/index.html".   I'm using .Net 2003 if that helps. Sign In·View Thread·Permalink
 Re: Good article peterchen 11 Jun '05 - 1:20
 Re: Good article CasualT 11 Jun '05 - 11:10
 Doxygen is better than Doc++ Jack Hwang 25 Feb '05 - 11:31
 I have used Doc++ for a while but not very happy with it. I find Doxygen is much better and easier to configure the output. Since I am moving to a new job that they do not use auto doc tools, I think I will recommend Doxygen to my colleagues. Sign In·View Thread·Permalink
 Probems to locate index entry. Ancy 18 Aug '04 - 22:01
 I have generated HTML files using Doxygen and compiled it using the HTML help workshop to create .chm file. It all worked well ...but when I try to locate a particular function name from the index list , it always ask to select the subentry to locate the function. But the subentry is the name of the module(file) in which the function is written.And when I click on this it always goes to the begining of the file , not to the function. How can I get to the function when I click on the function name? Please help.   With Warm Regards, Ancy Sign In·View Thread·Permalink
 There is also Doc++. axilmar 15 Aug '04 - 12:16
 Re: There is also Doc++. Timothy Madden 24 Dec '04 - 0:17
 How to document implementation in .cpp file with doxygen mihca2000 14 Jul '04 - 22:07