How to document your C++ Porgram by using Doxygen07/06/2019 Tags: C_C_plus_plus Doxygen
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:
- Open Terminal
$brew install doxygen
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.
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:
- Javadoc style: It is consist of a C-style comment block starting with two *'s, like this
- Qt style It adds an exclamation mark (!) after the opening of a C-style comment block, as shown in
/** * ... text ... */
/*! * ... text ... */
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…. ==========
If you have any constructive criticism or advises, leave the comments below or feel free to email me @email@example.com. Hope this post will help! :)