How to document your C++ Porgram by using Doxygen

[UPDATED: 2022/03/08]

Purpose

In order to quickly recap your code, documenting your code is one of the effective methods and also readable. Doxygen supports the de facto standard for creating documentation for C and C++ program, but it also supports other popular programming languages such as Java and Python. It also allows us to generate a fully structured set of HTML or Latex page from the program source code.

For avoiding to forget bit and pieces of using Doxygen, I recorded a few pieces of information and also put a simple C program and a simple C++ program which contain some Doxygen code snippets. Once processed with Doxygen, it gives C output and C ++ output. Hope this post would be helpful.

How to document your code

There are four steps that you should follow:

Generate doxygen

1. Install the doxygen on Mac OSX
2. Generate a configuration file
3. Document your code
4. Run doxygen to create the documentation

Install the doxygen on Mac OSX

1. Open Terminal
2. Run:

$brew install doxygen 

Generate a configuration file

By calling doxygen with the -g option in your project to generate a configuration file:

$doxygen -g < config_file > 

The configuration file is a free-form ASCII text file with a structure that is similar to that of a Makefile. The common configuration options are:

• PROJECT_NAME: - identify the project for which the documentation is generated.
• PROJECT_NUMBER: - enter a project or revision number
• INPUT: - specify the files and/or directories that contain documented source files.
• OUTPUT_DIRECTORY: - specify the path into which the generated documentation will be written.
• EXTRACT_ALL: - if this tag is set to YES, doxygen will assume all entities in documentation are documented.
• FILE_PATTERNS: - specify one or more wildcard patterns to filter out the source-files in the directories.
• INLINE_SOURCE: - tag to YES will include the body of functions, classs and enums directly into documentation.

You can refer to configuration and customize doxygen by yourself.

Document your code

For the C program, the actual documentation consists of comments you write in the .h and .c files that are based on the configuration of doxygen.

There are several ways to mark a comment block as a detailed description:

1. Javadoc style:
It is consist of a C-style comment block starting with two *'s, like this

/**
 * ... text ...
 */

2. Qt style
It adds an exclamation mark (!) after the opening of a C-style comment block, as shown in

/*!
 * ... text ...
 */

Run Doxygen to create the documentation

To generate the documentation you can now enter:

doxygen < config-file >

Depending on your setting Doxygen will create HTML, latex inside the output directory.

Configuration with Tag file

Doxygen also supports to link with of C++ names or STL libraries from external documantation via “TAGFILES” functionality. There are two ways to link with cppreference’s tag file:

• Using “location/of/cppreference-doxygen-local.tag.xml=/location/of/html/book/root/” to link with local archive
• Using “location/of/cppreference-doxygen-web.tag.xml=http://en.cppreference.com/w/” to link with cppreference.com.

For more details or downloading the HTML archive file, Archives for offline viewing is available to read more description and clear instruction.

=========== To be continued…. ==========

Reference

[1] Doxygen

[2] Doxygen - Configuration

[3] Documenting the code

[4] How to document your code using doxygen

[5] cppreference: Archives for offline viewing

Note

If you have any constructive criticism or advises, leave the comments below or feel free to email me @qazqazqaz850@gmail.com. Hope this post will help! :)