Doxygen: A Breath of Fresh Air for API Documentation

Any successful commercial code spawns vertical applications that need bits and pieces of its API. Whether you call them hooks, functions, entry points, subroutines, or what-have-you, the need to document them well arises simultaneously. Doxygen fits this scenario to a T. In fact, if you've ever used the popular Qt GUI or any project created with Qt, you've probably browsed a Doxygen-generated HTML page.

As soon as any small project has more than three or four programmers working on it, the need for some explanation about how the functions work arises. Whether you are working in C or C#, the same old bugaboo rears its ugly head: How do you keep the documentation of function parameters accurate and consistent with the actual use cases? With Doxygen, you extract the documentation directly from the sources, which makes it much easier to keep the documentation consistent with the source code.

A perhaps worse scenario is your company purchasing some code from a third-party vendor with scanty or no documentation. How do you get your head around this thing when there's no place to start? For this and many other scenarios, Doxygen should be part of your toolset.

Doxygen is the brainchild of Dimitri van Heesch, who made it available under the GNU General Public License. He has shepherded the project for the past decade, producing one of the world's most widely used documentation packagers.

Doxygen Speaks Your Language

As you may have guessed, Doxygen can get started with little or no source-code preparation. Of course, the more prep you add, the better the outcome. But, you can still do a first pass on nearly any C, C++, Java, Objective-C, IDL (CORBA or Microsoft), C#, or PHP project and get great results.

Most developers use Doxygen to produce HTML-based docs for public or private consumption. As you know, HTML isn't the most convenient (or professional, for that matter) output stream for everyone. Fortunately, Doxygen supports output in Rich Text Format (RTF) PostScript, hyperlinked PDF, Latex, compressed HTML, XML, and even crusty old Unix man pages (see Figure 1).

Figure 1. Diagram of How Doxygen Works

Generating Your First Docs

Start off by downloading some binaries built for your platform of choice; Win32, Linux, MacOS X, and Solaris 9 are readily available. If you use another platform besides those, you need to grab the source for a native recompile. At this point, you are ready to go.

The main tool you will use (daily) is doxygen.exe. However, you can get a running start by using the Doxywizard to create your initial configuration file. The configuration file drives everything that you do with Doxygen; it is the blueprint for what you want done. Doxytag, a tool that allows you to integrate (point at) other HTML docs outside the domain of your own project (for example, third-party libraries), won't be covered in this article, but it may be worth exploring.

Because you probably don't care to write a configuration file from scratch, you can ask Doxygen to spit out a template by entering the following on the command-line:

Doxygen -g template.cfg

Doxygen will produce a starting template for you. Again, if you prefer not to edit this file, you can use Doxywizard to create it based on your answers to a short questionnaire.

Now, open the template.cfg file and make it point to the location of your current project:


Part of the magic of Doxygen is that it has parsers built in for each of the target languages. It will base its knowledge of file type on the extension of each file in the directory (.CPP for C++ and so forth). By default, it wants to rip through all the files in the base directory and discover what it can. You can tame it by specifying specific regular expressions of filenames (FILE_PATTERNS) to add or remove (EXCLUDE_PATTERNS).

You also can direct it to write to specific places by adjusting the OUTPUT_DIRECTORY, for example:


You can apply two basic levels of scope to the Doxygen run:

  1. EXTRACT_ALL=YES: Creates documentation on everything, commented or not
  2. EXTRACT_ALL=NO: Creates documentation only on explicitly commented items

Doxygen: A Breath of Fresh Air for API Documentation

Documenting Your Own Code

All you need to do to take maximum advantage of Doxygen is add short comment markers, such as /, *, !, and <, around your parameters. It will produce a professional-looking documentation page with them. The source code will look a little funny at first, but you gradually become accustomed to it and will either type them automatically or cut-and-paste them as you go. Take a look at the following example:

#ifndef EMPLOYEE_H    // Prevent multiple inclusion
#define EMPLOYEE_H
#include <iostream>
#include <string.h>
#include <stdio.h>
#include "person.h"
const int MAX_DEPT_LEN = 11;
/*! \class student
    \brief represents a student enrolled in your college
     The student object is concrete class derived from the abstract
     base class person.
class student : virtual public person
   float GPA;    /**< Current Grade Point Average (GPA) */
   //! An enum.
   /*! Different types of majors we have at the college */
   enum studMajor {
      CompSci, /*!< Computer Science Major */
      CompSec, /*!< Computer Security Major */
      BsktWv   /*!< Basket-Weaving Major */
   //! default constructor
       Most important thing is to initialize GPA value!
   student() :
      person() {
         GPA = 0.0f;
   /// 3-arg constructor
   student(char *i_name,    ///< full name (Lastname, First, M.I
           int i_age,       ///< Age at time of enrollment in yrs
           float iGPA       ///< Initial value for GPA
              ) :
   person(i_name, i_age) {
   GPA = iGPA;

From this rather minimalist description, Doxygen generates this page. The page appears fairly simple, but it actually offers a lot to explore. For example, if you click on the "person" object in the Inheritance Diagram (that yellow rectangle), it will navigate you to the person object and you will see this:

If you clicked on "List of All Members," you would browse to this handy list, which of course includes all of the inherited members too:

Try maintaining this by hand!

Other cool things you can do with Doxygen include the following:

  • Automatically generate class and collaboration diagrams in HTML (as clickable image maps) and Latex (as Encapsulated PostScript images)
  • Use the dot tool of the Graphviz tool kit to generate include dependency graphs, collaboration diagrams, and graphical class hierarchy graphs
  • Include your own source code examples, which get automatically cross-referenced with the documentation
  • Add references to third-party documentation that was not produced by Doxygen
  • Insert inline HTML
  • Produce projects that are compatible with JavaDoc (1.1), Qt-Doc, and ECMA-334 (C# spec.)
  • Put your comments anywhere—in the .H files, sources files, or in a separate file

The .DOC Is In!

Maintaining proper code documentation for customers, internal use, and ISO 9000 requirements is never going to be a picnic. But, imagine getting a head start with an object-oriented documentation system that can regenerate a complete project doc in a few seconds, and you begin to understand why nearly 16 million pages of source code are already documented with Doxygen (according to a recent Google search). So what are you waiting for?

About the Author

Victor Volkman has been writing for C/C++ Users Journal and other programming journals since the late 1980s. He is a graduate of Michigan Tech and a faculty advisor board member for Washtenaw Community College CIS department. Volkman is the editor of numerous books, including C/C++ Treasure Chest and is the owner of Loving Healing Press. He can help you in your quest for open source tools and libraries, just drop an e-mail to

About the Author

Victor Volkman

Victor Volkman has been writing for C/C++ Users Journal and other programming journals since the late 1980s. He is a graduate of Michigan Tech and a faculty advisor board member for Washtenaw Community College CIS department. Volkman is the editor of numerous books, including C/C++ Treasure Chest and is the owner of Loving Healing Press. He can help you in your quest for open source tools and libraries, just drop an e-mail to


  • There are no comments yet. Be the first to comment!

Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • 10 Rules that Make or Break Enterprise App Development Projects In today's app-driven world, application development is a top priority. Even so, 68% of enterprise application delivery projects fail. Designing and building applications that pay for themselves and adapt to future needs is incredibly difficult. Executing one successful project is lucky, but making it a repeatable process and strategic advantage? That's where the money is. With help from our most experienced project leads and software engineers, …

  • Live Event Date: September 10, 2014 @ 11:00 a.m. ET / 8:00 a.m. PT Modern mobile applications connect systems-of-engagement (mobile apps) with systems-of-record (traditional IT) to deliver new and innovative business value. But the lifecycle for development of mobile apps is also new and different. Emerging trends in mobile development call for faster delivery of incremental features, coupled with feedback from the users of the app "in the wild". This loop of continuous delivery and continuous feedback is …

Most Popular Programming Stories

More for Developers

Latest Developer Headlines

RSS Feeds