Learn how to use doxygen to generate source code documents

Learn how to use doxygen to generate source code documents

Browsing times: 4 fonts: [Increase or decrease] type: reprint
Maintaining legacy systems developed with C/C ++ and adding new features is a difficult task. This involves several issues: Understanding the existing class hierarchy and global variables, different user-defined types, and function call graph analysis. This article discusses several features of doxygen through examples in the context of the C/C ++ project. However, doxygen is flexible and can be used for 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/C ++ source code, but it also briefly describes how to generate a code document using the tag defined by doxygen.

Install doxygen

There are two methods to obtain doxygen. You can download pre-compiled executable files, or download the source code from the svn repository and compile it yourself. Listing 1 demonstrates the latter method.

Listing 1. Install and build the 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: The configuration script stores the compiled source code in/home/user1/bin (this directory will be added to the PATH variable after compilation ), not every UNIX user has the write/usr folder permission. In addition, you need to use the svn utility to download the source code.

Use doxygen to generate documents

To generate source code using doxygen, You need to perform three steps.

Generate configuration file

On the shell prompt, enter the command doxygen-G. This command generates an editable configuration file doxyfile in the current directory. You can change the file name. In this case, call doxygen-G <user-specified file name>, as shown in Listing 2.

Listing 2. Generating the default configuration file

Bash-2.05b $ doxygen-G
Configuration File 'xyfile' 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 adopts a structure like <tagname >=< value>, similar to the Make file format. The following are the most important labels:

<Output_directory>: A directory name, such as/home/user1/documentation, must be provided here. This directory is the location where the generated file is stored. If a non-existing directory name is provided, doxygen creates a directory with the appropriate user permissions.

<Input>: This tag creates a list Of all directories separated by spaces. This list contains the C/C ++ source code files and header files to be generated. For example, consider the following code snippet: input =/home/user1/project/kernel/home/user1/project/memory

Here, doxygen reads the C/C ++ source code from these two directories. If the project has only one source code root directory with multiple subdirectories, you only need to specify the root directory and set the <recursive> flag to yes.

<File_patterns>: by default, doxygen searches for files with typical C/C ++ extensions, such as. C,. CC,. cpp,. H, and. HPP. Doxygen does this if the <file_patterns> flag is not associated. If the source code file adopts different naming conventions, the TAG should be updated accordingly. For example, if the project uses. c86 as the C file extension, you should add the extension in the <file_patterns> tag.

<Recursive>: if the source code hierarchy is nested and you need to generate a document for the C/C ++ file at all levels, set this flag to yes. For example, consider the source code root directory hierarchy/home/user1/project/kernel, the subdirectories include/home/user1/project/kernel/vmm and/home/user1/project/kernel/ASM. If this flag is set to yes, doxygen recursively searches the entire hierarchy and extracts information.

<Extract_all>: This tag tells doxygen to extract information even if each class or function has no documentation. You must set this flag to yes.

<Extract_private>: set this flag to yes. Otherwise, the document does not contain private data members of the class.

<Extract_static>: set this flag to yes. Otherwise, the document does not contain static members (functions and variables) of the file ).

Listing 3 shows a do

Xyfile example.
Listing 3. doxyfile example containing the user-provided tag Value

Output_directory =/home/user1/docs
Extract_all = Yes
Extract_private = Yes
Extract_static = Yes
Input =/home/user1/project/kernel
# Do not add anything here unless you need to. doxygen already covers all
# Common formats like. c/. CC/. cxx/. c ++/. CPP/. INL/. h/. HPP
File_patterns =
Recursive = Yes

Run doxygen

Enter doxygen doxyfile (or another file name selected for the configuration file) in the shell prompt to run doxygen. Before the documents in hypertext markup language (HTML) and latex format (default) are generated, doxygen displays several messages. During document generation, two subfolders, HTML and latex, are created in the <output_directory> tag specified folder. Listing 4 is a doxygen running log example.

Listing 4. doxygen log output

Searching for include files...
Searching for example files...
Searching for images...
Searching for dot files...
Searching for files to exclude
Reading input files...
Reading and parsing tag files
Preprocessing/home/user1/project/kernel. h
...
Read 12489207 bytes
Parsing input...
Parsing file/project/user1/project/kernel/epico. cxx
...
Freeing input...
Building Group list...
..
Generating docs for compound memorymanager: processspec
...
Generating docs for namespace std
Generating group index...
Generating example index...
Generating File member index...
Generating namespace member index...
Generating page index...
Generating graph info page...
Generating search index...
Generating style sheet...

Document Output Format

In addition to HTML, doxygen can also generate documents in several output formats. You can have doxygen generate documents in the following format:

Unix manual page: Set the <generate_man> flag to yes. By default, the man sub-folder is created in the directory specified by <output_directory>, and the generated documents are placed in this folder. You must add this folder to the manpath environment variable.

Rich Text Format (RTF): Set the <generate_rtf> flag to yes. Set the <rtf_output> flag to the directory where the. rtf file is to be placed. By default, the document is placed in the RTF sub-folder in output_directory. To support cross-Document Browsing, set the <rtf_hyperlinks> flag to yes. If this tag is set, the generated. rtf file contains cross-document links.

Latex: by default, doxygen generates latex and HTML documents. In the default doxyfile, the <generate_latex> flag is set to yes. In addition, the <latex_output> flag is set to latex, which means that the latex sub-folder will be created in output_directory and the latex file will be generated in it.

Microsoft Compiled HTML Help (CHM) Format: Set the <generate_htmlhelp> flag to yes. Because this format is not supported on UNIX platforms, doxygen generates an index. HHP file only in the folder where HTML files are saved. You must use HTML to help the compiler convert this file to a. CHM File.

Extensible Markup Language (XML) Format: Set the <generate_xml> tag to yes. (Note: doxy

Gen development team is still developing XML output ).
The doxyfile example provided in listing 5 allows doxygen to generate documents in all formats.

Listing 5. Generating doxyfile for documents in multiple formats

# For HTML
Generate_html = Yes
Html_file_extension =. htm
# For CHM files
Generate_htmlhelp = Yes
# For latex output
Generate_latex = Yes
Latex_output = Latex
# For RTF
Generate_rtf = Yes
Rtf_output = RTF
Rtf_hyperlinks = Yes
# For man pages
Generate_man = Yes
Man_output = man
# For XML
Generate_xml = Yes

Special mark in doxygen

Doxygen contains several special tags.

Preprocessing of C/C ++ code

To extract information, doxygen must pre-process the C/C ++ code. However, by default, it only performs partial preprocessing-the computing condition compilation Statement (# If... # Endif), but do not execute macro expansion. Consider the code in Listing 6.

Listing 6. Use the macro C ++ code example

# Include <cstring>
# Include <rope>
# Define use_rope
# Ifdef use_rope
# Define string STD: Rope
# Else
# Define string STD: String
# Endif
Static string name;

The document generated by doxygen is as follows:

Defines
# Define use_rope
# Define string STD: Rope
Variables
Static string name

Here, we can see that doxygen executes Conditional compilation, but does not execute macro expansion on string. The <enable_preprocessing> flag in doxyfile is set to yes by default. To execute macro expansion, set the <macro_expansion> flag to yes. This causes doxygen to generate the following output:

Defines
# Define use_rope
# Define string STD: String
Variables
Static STD: Rope name

If you set the <enable_preprocessing> flag to no, the doxygen output of the source code is:

Variables
Static string name

Note that the document is not defined now and the string type cannot be exported. Therefore, you should always set the <enable_preprocessing> flag to yes.

In this document, you may want to expand only specific macros. Therefore, in addition to setting the <enable_preprocessing> and <macro_expansion> tags to yes, you must also set the <expand_only_predef> tag to Yes (this tag is set to no by default ), the macro details are provided in the <predefined> or <expand_as_defined> mark. Consider the code in listing 7. Here you only want to expand the macro container.

Listing 7. c ++ source code that contains multiple macros

# Ifdef use_rope
# Define string STD: Rope
# Else
# Define string STD: String
# Endif
# If allow_random_access = 1
# Define container STD: Vector
# Else
# Define container STD: List
# Endif
Static string name;
Static container Glist;

Listing 8 shows the configuration file.

Listing 8. doxyfile that allows you to expand macros selectively

Enable_preprocessing = Yes
Macro_expansion = Yes

Expand_only_predef = Yes
Expand_as_defined = container
...
The following doxygen output only expands the container:

Defines
# Define string STD: String
# Define container STD: List
Variables
Static string name
Static STD: List glist

Note that only the container macro is expanded. When both <macro_expansion> and <expand_only_predef> are set to yes, the <expand_as_defined> flag only selects the macros listed on the right of the expand equal sign operator.

The last mark for preprocessing is <predefined>. Just like using the-D switch to pass the pre-processor definition to the C ++ compiler, use this tag to define the macro. Consider doxyfile in listing 9.

Listing 9. Defining the extended doxyfile

Enable_preprocessing = Yes
Macro_expansion = Yes
Expand_only_predef = Yes
Expand_as_defined =
Predefined = use_rope =
Allow_random_access = 1

The output generated by doxygen is as follows:

Defines
# Define use_crope
# Define string STD: Rope
# Define container STD: Vector
Variables
Static STD: Rope name
Static STD: vector glist

When <predefined> is used, the macro should be defined as <macro name >=< value>. If no value is provided, for example, simple # define, use <macro name >=< spaces>. Multiple macro definitions are separated by spaces or backslash.

Exclude specific files or directories from document generation

In the <exclude> mark in doxyfile, add a file or directory (separated by spaces) that should not be generated for the file ). Therefore, it is useful to provide the root of the source code hierarchy and skip some subdirectories. For example, if the root of the hierarchy is src_root and you want to skip the examples/and test/memoryleaks folders during document generation, doxyfile should be like Listing 10.

Listing 10. doxyfile marked with exclude

Input =/home/user1/src_root
Exclude =/home/user1/src_root/examples/home/user1/src_root/test/memoryleaks
...

Generate graphs and charts

By default, doxyfile sets the <class_diagrams> flag to yes. This tag is used to generate a class hierarchy chart. To generate a better view, you can download the dot tool from the graphviz download site. The following mark in doxyfile is used to generate a chart:

<Class_diagrams>: In doxyfile, the flag is set to yes by default. If this flag is set to no, the hierarchy structure is not generated.

<Have_dot>: If this flag is set to yes, doxygen uses the dot tool to generate more powerful graphs, such as collaboration diagrams that help understand class members and their data structures. Note: If this flag is set to yes, the <class_diagrams> flag is invalid.

<Class_graph>: if both the

<Collaboration_graph>: if both the

Listing 11 provides an example of using some data structures. Note: In the configuration file, the

Listing 11. c ++ class and structure example

Struct d {
Int D;
};
Class {
Int;
};

Class B: Public {
Int B;
};
Class C: Public B {
Int C;
D;
};
Figure 1 shows the doxygen output.

Figure 1. class inheritance graph generated using the dot tool and co-Drawing

Code Document Style

So far, we have used doxygen to extract information from the code without any documentation. However, doxygen also encourages the use of document styles and syntaxes, which helps to generate more detailed documents. This section describes some common markup that doxygen encourages in C/C ++ code. For more information, see references.

Each code element has two descriptions: Brief and detailed. A brief description is usually a single line. There is also a third in-body description (in-body description) for functions and class methods, which aggregates all the comment blocks found in the function body. Some commonly used doxygen markup and annotation styles are as follows:

Brief description: Use a single line of C ++ comments, or use the <brief> flag.

Detailed Description: Use javadoc Annotations /**... Test... */(Note the two asterisks [*] At the beginning) or the QT-style comments /*! ... Text... */.

Body Description: Class, structure, Consortium, namespace, and other C ++ elements all have their own tags, such as <class>, <struct>, <Union>, and <namespace>.

To generate a document for global functions, variables, and enumeration types, you must first use the <File> flag for the corresponding file. The example in listing 12 contains four elements: function tag (<FN>), function parameter tag (<param>), and variable name tag (<var>), used for # define mark (<def>), and used to indicate problems related to a code snippet (<warning> ).

Listing 12. Typical doxygen mark and Its Usage

/*! File globaldecls. h
Brief place to look for global variables, enums, functions
And macro definitions
*/
/** Var const int filesize
Brief default size of the file on disk
*/
Const int filesize = 1048576;
/** Def shift (value, length)
Brief left shift value by length in bits
*/
# Define shift (value, length) (value) <(length ))
/** FN bool check_for_io_errors (File * FP)
Brief checks if a file is already upted or not
Param FP pointer to an already opened file
Warning NOT thread safe!
*/
Bool check_for_io_errors (File * FP );

The generated documents are as follows:

Defines
# Define shift (value, length) (value) <(length ))
Left shift value by length in bits.
Functions
Bool check_for_io_errors (File * FP)
Checks if a file is already upted or not.
Variables
Const int filesize = 1048576;
Function documentation
Bool check_for_io_errors (File * FP)
Checks if a file is already upted or not.
Parameters
FP: pointer to an already opened file
Warning
Not thread safe!

Conclusion

This article discusses how to use doxygen to extract a large amount of related information from the legacy C/C ++ code. If you use the doxygen tag to generate code documents, doxygen generates output in a readable format. Doxygen can help any developer maintain and manage legacy systems in an appropriate way.