Ask The Oracle

...A Tech blog for Engineers, Software Devs, and Computer Geeks

Document Your Software the Easy Way with Doxygen

Written by BobW on April 12th, 2010

Many software developers like writing code but hate writing documentation for it. There is a free program called Doxygen that can generate the documentation for you and safe you time and heartache.

Doxygen is an open source tool that can generate printed or online documentation from your source. It works for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#.  It is supported on Windows, Linux, and Mac OS X. It can really take the drudgery out of documentation and generates a high quality documentation manual for your software. As long as you keep your function and fie headers up to date as you modify your code, you can instantly generate up to date documentation.

Here are some links to show real examples of documentation generated by Doxygen.

Doxygen comes with extensive documentation, but lacks a quick start manual for new users. This can make it look harder and more intimidating to use than it actually is. Once you set it up and learn a few easy rules, great documentation becomes an easy task. In this post, I want to point you to some information that will get you up and running in no time.

Tutorials
Doxygen Tutorial
Here is another quick start tutorial for Visual C++ users:
10 Minutes to Document your Code

Example Header comments for use with Doxygen

You can run Doxygen without making any changes to your source. However, to get the maximum benefit from this software, you need to include some tags to help Doxygen extract important information from your code. It is actually easy to modify your function headers to work with Doxygen.  Here is an example function header.

Function Header

/****************************************************************/
/** @brief
*        <Enter 1 line description here>
*
*   @details
*        <Enter detailed description here>
*
*   @param [in] <parameter name> <parameter description>
*
*   @param [out] <parameter name> <parameter description>
*
*   @return <describe return value>
*
****************************************************************/

The tags that begin with ‘@’  (@brief, @details, @param, etc.) are the keywords that tell Doxygen how to extract information. There are many more tags you can use, but these will get you started. If you don’t have an input (or output) variable then delete the appropriate @param line. The special tag /** tells signals the start of Doxygen tags. Replace anything within < > with your information, which can span multiple lines.

Here is an example File Header

/****************************************************************/
/** @file       <Filename>
*    @brief      <Brief description of what the file does>
*
*    @note       (c) Copyright 2010, Oracle Engineering Inc,
*                         www.AskTheOracle.com \n
*                         All Rights Reserved.
*
****************************************************************/

Of course, you can add fields and put your own copyright notice.  There are many other possible formats (read the docs) to set up these headers.  These are presented to give you a quick start. Put these (or you own) headers into the file and Doxygen will do the rest generating beautiful, up to date documentation.

If you have hints, templates or links to Doxygen tuturials, please share them in the comments section.

0 Comments so far ↓

  1. […] a previous post, I discussed how to use Doxygen to create documentation for you software project.  This post shows […]

You must be logged in to post a comment.