C++: Creating Documentation with Doxygen

Most programmers hate to create documentation even more than they hate to comment their own code. Enter Doxygen, which enables programmers to embed tags in the comments that can later be extracted to create the documentation.

Installing Doxygen

Doxygen does not come with Code::Blocks (at least not as of this writing). You'll need to download the proper version of Doxygen for your application. (There's also a link to the Doxygen website from the Code::Blocks site.) After you link to Doxygenorg website, you can navigate to the download page and find the version of Doxygen for your operating system, as shown here:

image0.jpg

Download and install the version that's right for your operating system. You can accept the defaults, but remember where the installation wizard puts the Doxygen executable file.

Now start Code::Blocks. Select DoxyBlocks→Open Preferences. From there select the General tab and set the Path to Doxygen. (This is the path that you noted in the previous paragraph.) The default path for Windows is C:\Program Files\doxygen\bin\doxygen.exe. Do the same for the Path to Doxywizard. Here the default for Windows is C:\Program Files\doxygen\bin\doxywizard.exe. You can leave the other tools blank as they are not needed when generating documentation in HTML format.

Adding Documentation Comments

Doxygen uses special comments to flag keywords that help the tool create documentation. Confusingly enough, Doxygen accepts several different standards, but the default is the one that looks most like JavaDoc, the /** comment, which is fine. (You can change the comment style to one of the others by selecting DoxyBlocks→Open Preferences and then selecting the Comment Style tab.)

To see how this works, place the cursor at the beginning of a function and select DoxyBlocks→Block Comment (or press Ctrl+Alt+B). A comment like the following appears (the following examples are using the Budget5 program that appears in the downloadable material at www.dummies.com/extras/cplusplus):

/** \brief 
 *
 * \param accList list<AccountPtr>&
 * \return void
 *
 */    
void getAccounts(list<AccountPtr>& accList)
{

Code::Blocks inserts a Doxygen block comment starting with /**. Doxygen knows that this comment belongs to the function definition that immediately follows. Doxygen keywords start with a \ (backslash). The \brief keyword flags the brief description of the function. The brief description can extend over more than one line. This should be a short description of the function that appears in tabular displays.

The programmer can follow this with a more thorough description flagged with the \details keyword. This detailed description gives a more thorough description of what the function does.

Many of the Doxygen keywords are optional. In particular, the \details keyword is assumed if you start a paragraph separated from the \brief description by nothing more than a blank line.

Beyond that is a separate line flagged with the keyword \param to describe each argument to the function. Finally, the \return keyword describes the value returned by the function.

When filled out, the Doxygen comment for getAccounts() might appear as follows:

/** \brief getAccounts - inputs accounts from the keyboard
 * \details This function reads input from the keyboard.
 * For every S or C entered, the function creates a new
 * Savings or Checking account object and adds it to the
 * account list. An X terminates the entry. Any other
 * input is assumed to be a deposit (numbers greater than
 * 0) or a withdrawal (numbers less than 0).
 *
 * \param accList list<AccountPtr>& the list of account
 *                objects created by getAccounts()
 * \return void
 */
void getAccounts(list<AccountPtr>& accList)
{

You can also add a Doxygen comment on the same line. This is most often used when commenting data members. Place the cursor at the end of the line and either select DoxyBlocks→Line Comment or press Ctrl+Alt+L. Now fill in a description of the data member. The result appears as in the following example also taken from Budget5:

    double   balance;/**< the balance in current account*/

Generating Doxygen documentation

Doxygen can generate documentation in several different formats, though some (such as compiled HTML) require further downloads. The HTML format is particularly convenient since it requires nothing more than a browser to view.

The default is HTML, but if you want to change the format select DoxyBlocks→Open Preferences, then select the Doxyfile Defaults 2 tab. In this window you can select all of the different formats that you want to generate.

Before extracting documentation the first time, you will probably want to select a few other options. Select DoxyBlocks→Open Preferences, and then select the Doxyfile Defaults tab. Make sure that the Extract All box is checked. Next select the Doxyfile Defaults 2 tab and check the Class_Diagrams check box. Now select the General tab and check the Run HTML After Compilation box. Click OK, and you're done. (You won't need to do this again as the options are saved in a file called doxyfile.)

Select DoxyBlocks→Extract Documentation to generate and view the documentation. After a fairly short interval, Doxygen opens up your favorite browser with documentation like that shown in the following figure.

Doxygen is not very user friendly when it comes to input errors. Sometimes Doxygen just stops generating documentation at some point in your source for no obvious reason. Check the doxygen.log file contained in the same directory as the doxyfile for any errors that may have occurred during extraction.

The following image shows the project browser in the left window that allows the user to navigate within the project's documentation. On the right, the getAccounts() function has been selected in order to get a more detailed description. The brief description appears on the first line, followed by the detailed description, the parameters, and the return value:

image1.jpg

The class documentation is similarly thorough as shown by the following code snippet.

/** \class Account
 *  \brief an abstract bank account.
 *  \details This abstract class incorporates
 *         propertiescommon to both account types:
 *         Checking and Savings. However, it's missing the
 *         concept withdrawal(), which is different
 *         between the two
 */
class Account
{

The documentation for Account is shown here:

image2.jpg

Notice the description that appears under the class Account. This is the brief description. Clicking More will take you to the detailed description. Also notice the graphical representation of the inheritance relationship between Account, its parent classes, and its children classes.

  • Add a Comment
  • Print
  • Share
blog comments powered by Disqus
Advertisement

Inside Dummies.com

Dummies.com Sweepstakes

Win $500. Easy.