December 17, 2014
Hot Topics:

Doxygen: A Breath of Fresh Air for API Documentation

  • September 1, 2006
  • By Victor Volkman
  • Send Email »
  • More Articles »

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
{
private:
   float GPA;    /**< Current Grade Point Average (GPA) */
public:
   //! 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 sysop@HAL9K.com.





Page 2 of 2



Comment and Contribute

 


(Maximum characters: 1200). You have characters left.

 

 


Enterprise Development Update

Don't miss an article. Subscribe to our newsletter below.

Sitemap | Contact Us

Rocket Fuel