Вы находитесь на странице: 1из 13

Articles General Programming Programming Tips General

10 Minutes to document your


code
peterchen, 19 Jan 2003

CPOL

4.91 154 votes

Setting up doxygen, a free tool to document your code, in a


few simple steps.

Download doxygen helper files 20 Kb


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 oneclick 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 stepbystep guide to setting up
and integrating doxygen with VC++ 6
2. Documenting Basics hot to make doxygen understand
your comments.
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

You're done! Try!

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 /
<project name>". If you use
VSS, I'd also add it to
SourceSafe
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:
///SNAPINFOholdsthedataforcalculatingamodified
windowrect.Sinceit
///onlyworksoncoordinaterects,itcanbeused
withoutanyactualWindows.
structSNAPINFO
{
//...
}

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
structSNAPINFO
{
///Init,usingaprechangeandapostchange
rectangle
voidInit(RECTconst&oldRect,RECTconst&
newRect,DWORDsnapwidth);
voidSnapHLine(inty);///<spanclass="code
SummaryComment"><Snaptoahorizontalline
}</span>

3. Add a detailed description to the method


implementation
as with classes, use a /// comment block
///Initializesthestructurewithanoldananew
rectangle.
///usethismethodifthewindowisabouttobemoved
orresized(e.g.in
///WM_SIZINGorWM_MOVINGhandler)
voidInit(RECTconst&oldRect,RECTconst&newRect,
DWORDsnapwidth)
{
//...
}

I prepared an example for a small class of another article,


which had virtually no documentable comments.
original code [^]

documentation
[^]

brief comments
added [^]

13 new lines
documentation
2 with comment style
[^]
modified

method
14 additional lines
documentation
desciptions added
with ehavy
[^]
[^]
copy&paste
without
EXTRACT_ALL
option

documentation
[^]

Note: as soon as you have added a basic doxycomment 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 coworkers 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 uptodate
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.
Incode comments carry important meta
information
Not all important information is available from the
actual "raw" source code. Interface contracts, pre and
postconditions, 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
doubleclick 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 doxygenstyle 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 nonexisting 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 in
You 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.
Indictaes that the following

\mainpage

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
More...
doxygen documentation the XML export. e.g. you can
makr the specificaiton of pre
and postconditions, bugs, test
cases, todo's, etc.
Doxygen also supports HTML
tags, which get converted to
HTML
doxygen documentation other outputs mroe or less
correctly.

Additional Resources
Macros:
It's convenient to set up some autotext 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
CtrlEnter
comments just press Ctrl
Enter instead of just Enter

'///< ' : for brief


DoxyCommentPrev comments behind the
declaration
DoxyDocFunction

a simple header to
comment a function

CtrlShift#

CtrlShiftF

Style Sheets:
You can generate a default doxygen style sheet, HTML header
and footer by calling
doxygenwhtml<header_name><footer_name>
<stylesheet_name>

I did this for you already: doxygen_header.html,


doxygen_footer.html, and doxygen_default.css.
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 disrecommend 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.

License
This article, along with any associated source code and files, is
licensed under The Code Project Open License CPOL

Share
About the Author
peterchen
Klippel
Germany

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


170 messages have been posted for this article Visit
http://www.codeproject.com/Articles/3528/Minutesto
documentyourcode to post and view comments on this article,
or click here to get a print view with messages.
Permalink | Advertise | Privacy | Terms of Use | Mobile
Web01 | 2.8.150331.1 | Last Updated 20 Jan 2003

Select Language

Article Copyright 2003 by peterchen


Everything else Copyright CodeProject, 19992015