C++ Reference Material
Getting Started with Doxygen

What is doxygen?

If by any chance you already know what the javadoc tool does for you when writing Java programs, then the easiest way to describe doxygen in the current context is to say that doxygen is to C++ as javadoc is to Java.

If that analogy means nothing to you, then we should say that doxygen is a software utility that recognizes comments within C++ code that have a certain form, and uses them to produce a collection of HTML files containing the information in those comments. For this to be useful, of course, that information should be documentation for the surrounding source code, and this then allows the developer to place that documentation within the source code being documented. This in turn gives the developer much quicker access to the documentation and provides a greater incentive to keep the documentation up to date.

Some doxygen syntax

The first thing to note about the doxygen utility program is that it ignores C++ comments having either of the two usual forms(// ... or /* ... */).

But ... there are two kinds of special comments recognized (and processed) by doxygen:

  1. Comments that start with a /** delimiter and end with a */ delimiter.
  2. Comments that start with a /**< delimiter and end with a */ delimiter.

Here's the difference between the two: Use the first one if you want to place the comment before the thing you are commenting, but use the second one if you want to place the comment after the thing you are commenting.

The content of a comment having either of these syntactical forms might be just some text (one or two sentences describing whatever is being commented, for example), or some text like that plus some other text marked by special markers called tags, which we discuss below.

For example, here is a doxygen comment:

/**<
This comment is not only a C++ comment since it has the starting and ending
delimiters of a C-style C++ comment, but because of the extra characters at
the end of the starting delimiter it also will be recognized by the doxygen
utility and given special treatment. By the way, that last (optional) <
character at the end of the opening delimiter is critical if you want to place
the doxygen comment *after* the thing you are documenting. If that final < is
missing, the comment is interpreted as coming before the thing being documented.
*/

A doxygen tag is a keyword preceded by the @ symbol. Tags are used inside a doxygen comment to document special parts of the source code (such as a function return type or a function parameter), or to designate additional information (such as author and version number) that you wish to appear as part of the documentation. Text identified by tags is formatted in special ways by doxygen in its HTML output files.

Here is a list of some of the most frequently used doxygen tags: 

@file              @return
@author            @param
@date              @pre
@version           @post
@mainpage          @throw

The tags in the first column above are used for documenting an individual file, or a project, while those in the second column are used for documenting a function.

Some other useful doxygen notes:

  1. The dash or hyphen (-) is used to denote a list item, which will be a bulleted item by default, but if you wish to have your list items automatically numbered, use -# instead.
  2. Putting a period on a line by itself will terminate a list, if you line it up with the beginning of the list items in the list that you wish terminated. Each - or -# is placed in front of the item it identifies, is followed by a blank space, and is aligned with all the other similar items for the same list. Lists can also be nested. If a second list is nested inside a first list, the items in the second list should be indented with respect to the items in the first list.
  3. Many ordinary HTML tags can also be used (<b></b> to make a word bold, for example).
  4. The doxygen tool produces HTML files, and because of the way whitespace is treated in HTML you may from time to time have to "force" line breaks in your HTML output files. You can do this in several ways, depending on the situation. Sometimes leaving a blank line in the input does the trick. You can also use the HTML <br> tag. Somewhat counter intuitively (if you are familiar with HTML), you can also use a \n character in your doxygen comments.

An example

A short, and incomplete, example of doxygen documentation is provided in the source code of the sample file doxygen_example.cpp. For a more complete example, check out the documentation for the instructor-supplied utilities package as you continue to use it. You will also find some additional doxygen comments in some of the sample code used to illustrate our C++ programming style conventions under "Rules + Guidelines: Coding Style"

In the short example given above, look for the above-mentioned doxygen comments and tags, as well as some HTML tags, and then study the corresponding HTML output to see the effect of each tag. This you can do by clicking on html which will take you to the index.html file in the html subdirectory produced from this program by the doxygen tool.

How to produce HTML documentation files from source code files containing doxygen comments

When the doxygen tool processes one or more input source code files, it produces, by default, in the current working directory, a subdirectory named html, which contains all the HTML files that document that source code, according to the doxygen comments contained in the source code. The starting point for browsing this documentation, as you might expect, is the file index.html.

For the above example, to produce the html directory and all the files in it, you just have to put the two files doxygen_example.cpp and the doxygen configuration file doxyconfig in the directory where you want the html directory to appear, and then enter this command: 

prompt> doxygen doxyconfig

The doxygen configuration file for any source code file or project can have any name you like. However, it will generally be convenient to give a configuration file for a given source code file or a given project a name that shows its connection with that file or project. If you look at the configuration file for the example you can easily see that for a different project you will want to change the values of PROJECT_NAME, PROJECT_NUMBER and INPUT, but you can probably leave the other parameter values set as they are. Note that INPUT contains a whitespace separated list of all files that you want doxygen to process.

On-Line References

  1. Doxygen home page You may get all the detailed information you need, as well as the latest version of doxygen itself from this site.
  2. You also have a very good example of doxygen at work in the HTML documentation for the C++ utilities package. You should know where that is and be referring to it frequently!