Installing Doxygen

Installing on Linux

Most Linux distributions will have Doxygen and GraphViz in the package manager somewhere (if your distribution doesn't have a package manager, either you live in the stone age, or you really know what you're doing, so either you need to join us in the present, or you don't need this guide ;) ).

So, to install the two packages, simply search for them in your package manager's interface (whatever it is), and install them. If you find a package called doxygen-wizard, doxygen-gui or something similar, install that as well, as you will probably enjoy having a nice GUI tool for editing the options. Don't worry, they are all there, nothing you can't do in the interface that is possible by editing the Doxyfile by hand.

Installing on Windows

This is going to look a little odd - me describing how to install Doxygen on Windows. However, as we all know, a lot of people still use this (for whatever reason they might have) and well... i was asked to write it ;)

• Download Doxygen from http://www.stack.nl/~dimitri/doxygen/ (writing moment that is the blue box in the right side).

• Grab the newest version of the installer and just follow the wizard to install.

• Download GraphViz from http://www.graphviz.org/ (writing moment that is the second link in the menu on the left side)

• Grab the newest version of the installer for Windows (the .exe, not the tar.gz), and just follow the wizard

There you go, that should leave you installed!

Using Doxygen

These instructions are essentially the same, never mind operating system, since the user interface, Doxywizard, is identical on all platforms (gotta love that Qt toolkit...).

Initial setup

Setting up your project the first time is fairly simple, but i'll just walk through a couple of good points to make a note of:

Project

• Project name and version are just that, they'll show up in the top of the index page of your HTML documentation

• Source code directory: Leave this empty, but check Scan recursively. This will cause the Doxyfile to simply read the current directory and work bellow that. Nifty trick if you're sharing the file with others!

• Destination directory: Write ./documentation in here. This will create a subdir under the current directory called documentation, where it will create subdirs for each of the output types you select in the Output tab

Mode

• Extraction mode: Select All entities here, and make sure the checkbox is checked

• Optimization: Select your language. Note that if you select C#, it will currently just default back to Java. However, the C# mode is being worked on, and it already works fine. Just set it to C# for now, you won't be using the Wizard dialog again anyway from here on.

Output

Select which type of output you want. This will probably just be HTML for most things you work on, so go with that. Also, you may find the frames and navigation tree mode interesting, but there's better control of these options in the Expert mode anyway.

Diagrams

This is where your newly installed GraphViz comes in. Select the "Use dot tool from the GraphViz package to generate" option, and check all the options. This will give you a nice, pretty set of clickable graphs all over your documentation, in appropriate places.

Expert options

Each section bellow is a small list of options of special interest to the new user. If you find one or the other option interesting, be sure to let your mouse hover - everything is tooltipped!

Project

This tab contains little of interest to the normal user

Build

Here you can select what to build the documentation from.

Extract options

Most interesting to a person using a framework such as .NET to create their software with is the EXTRACT options. Here you want to uncheck EXTRACT_ALL and select the other EXTRACT options in stead. They may seem to indicate the same meaning, however doing this will cause doxygen to not include the system namespace, which would otherwise be cluttering up everything.

Sort options

Take note of each of these options and their implications for listing sort order. If you do not check any of these, everything will be listed in order of declaration.

Generation options

These options are especially interesting for when your documentation is automatically generated. TODOLIST, TESTLIST, BUGLIST and DEPRECATEDLIST will each create markers identifying when one of those four markers are used. Deprecated is especially interesting, as marking one function deprecated using the doxygen tag \deprecated will cause each function using a deprecated function to be marked, so you can spot them easily.

Show options

Most projects these days fill up several directories. As such, you might wish to check these options as well.

Messages

Each of these options will make Doxygen generate more or less output. For projects such as university projects, especially the WARN_IF_UNDOCUMENTED option is interesting. For autogenerating code, the QUIET option will be interesting, since it will only give you output if there is an actual error.

Input

The input directory should ideally be ./ so that your Doxyfile isn't tied to one machine, and the RECURSIVE option checked. See the Initial setup section above.

If you use the \example option anywhere in your code (to provide sample code from external files), you will need to point EXAMPLE_PATH to that directory. This, as all other directory definitions, accept relative paths. So you can add for example ./src/examples to this, and it will work just fine.

Source browser

Depending on your temper, any of these options will work - however, make sure to actually include the source code, that is, check the SOURCE_BROWSER option.

The STRIP_CODE_COMMENTS option is noteworthy, however: It does NOT mean that your normal comments will be removed. It will simply cause the Doxygen tags to disappear, since they are already available elsewhere. Note also, that this option will keep the source code line numbers correctly to the actual source code.

Index

The Index option can be interesting, as the tooltip reads: If the project contains a lot of classes, structs, unions or interfaces. It simply contains an alphabetically ordered list of all compounds in the project.

HTML

Interesting options here include the HTML_HEADER, HTML_FOOTER and HTML_STYLESHEET which can be used to embed custom code into your documentation. This can be used to make the docs look consistent with a homepage for a project.

Also interesting is the GENERATE_TREEVIEW option, which will cause a tree-view to be generated, put in the left side of the window. However, this requires a lot of things for the browser, and so some users might find the GENERATE_CHI option more interesting. This option will generate a Windows compiled html help file. This, of course, is a lump file, and cannot be put online.

LaTeX, RTF, Man, XML, DEF, PerlMod, Preprocessor, External

Some options that i will not go into here (quite simply because i've not used them).

Dot

This is the little program that makes it possible to generate class diagrams and so on. In short, check every option in here, and make sure that your DOT_PATH points to the correct place. On Linux, this is generally fine, as your dot will generally be in the path (if not, see reason for not telling you in section 1). On Windows, this will be where you installed your GraphViz. The default for this is C:/Program Files/ATT/GraphViz/bin - take note of the bin at the end! It needs to point to the actual directory where the dot binary is, not just the installation directory itself.

Search

If you plan to put the HTML output online, you can enable this to make doxygen integrate a PHP based search engine into the site.

Download

• Download a sample Doxyfile As created for our uni project

Thanks

• Kurt Nørmark - Computer Science tutor at Aalborg University, teaching programming. He's the one who asked for this document... Little did he know how much i babble on ;)

• Dimitri van Heesch - For making Doxygen! A wonderful idea, thanks! :)