Learn to generate source documents with Doxygen

It is a difficult task to maintain legacy systems developed with C/s and add new features. This involves several issues: Understanding existing class hierarchies and global variables, different user-defined types, and function call graph parsing, and so on. This article discusses several features of Doxygen through examples in the context of a C + + project. However, Doxygen is very flexible and can also be used in software projects developed in Python, Java, PHP, and other languages. The main purpose of this article is to help you extract information from the C + + source code, but it also briefly describes how to generate code documents with Doxygen-defined tags.

Install Doxygen

There are two ways to get doxygen. You can download a precompiled executable or download the source code from the SVN repository and compile it yourself. Listing 1 shows the latter method.

Listing 1. Installing and building Doxygen source code

bash-2.05$ svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk doxygen-svn
bash-2.05$ cd doxygen-svn
bash-2.05$ ./configure –prefix=/home/user1/bin
bash-2.05$ make
bash-2.05$ make install

Note that the configuration script stores the compiled source code in/home/user1/bin (when compiled, the directory is added to the PATH variable) because not every UNIX® user has permission to write/usr folder. In addition, you need to download the source code with the SVN utility.

Using Doxygen to generate documents

A document that uses Doxygen to generate source code needs to perform three steps.

Build configuration file

On the shell prompt, enter the command doxygen-g. This command generates an editable configuration file Doxyfile in the current directory. This file name can be changed, in which case the doxygen-g <user-specified file name> should be called, as shown in Listing 2.

Listing 2. Generate the default configuration file

bash-2.05b$ doxygen -g
Configuration file 'Doxyfile' created.
Now edit the configuration file and enter
　doxygen Doxyfile
to generate the documentation for your project
bash-2.05b$ ls Doxyfile
Doxyfile

Edit configuration file

The configuration file uses a structure such as <TAGNAME> = <VALUE> similar to the make file format. The following are the most important tags:

<OUTPUT_DIRECTORY>: You must provide a directory name here, such as/home/user1/documentation, where you place the generated document files. If you provide a directory name that does not exist, Doxygen creates a directory with the appropriate user rights with that name.

<input>: This tag creates a list of all the directories separated by spaces that contain the C + + source code files and header files that need to generate the document. For example, consider the following code fragment:INPUT = /home/user1/project/kernel /home/user1/project/memory

Here, Doxygen will read the C + + source code from both directories. If the project has only one source root directory, which has multiple subdirectories, simply specify the root directory and set the <RECURSIVE> tag to Yes.

<file_patterns>: By default, Doxygen searches for files with a typical C + + extension, such as. C,. CC,. cpp,. h and. hpp. Doxygen does this if the <FILE_PATTERNS> tag does not have a value associated with it. If your source code file uses a different naming convention, you should update the tag accordingly. For example, if your project uses. C86 as the C file name extension, you should add the extension to the <FILE_PATTERNS> tag.

<recursive>: If the source code hierarchy is nested, and you need to generate a document for C + + files on all levels, set this tag to Yes. For example, consider the source code root hierarchy/home/user1/project/kernel, which has/HOME/USER1/PROJECT/KERNEL/VMM and/home/user1/project/kernel/asm Such subdirectories. If this tag is set to Yes,doxygen, the entire hierarchy is searched recursively and the information is extracted.

<extract_all>: This tag tells Doxygen to extract information even if each class or function does not have a document. This tag must be set to Yes.

<EXTRACT_PRIVATE>: Set this tag to Yes. Otherwise, the document does not contain private data members of the class.

<EXTRACT_STATIC>: Set this tag to Yes. Otherwise, the document does not contain static members (functions and variables) of the file.