Doxygen Generating Source Documents

Using Doxygen to generate the source code of the document is quite convenient, this article is simple to organize the use of Doxygen instructions

1. Installation

About the installation of the problem does not do special instructions, the use of direct installation here, source installation does not introduce

Ubuntu:

sudo Install Doxygen

Centos

sudo Yum Install Doxygen

2. configuration file Configuration

The main part about Doxygen is the configuration file configuration, Doxygen is quite powerful, so the configuration file content is a bit more. This is only part of the presentation, and we are interested in further research.

(1) Important marks

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

　　<OUTPUT_DIRECTORY> : A directory name must be provided here, such as/home/user1/documentation, which is the location where the generated document files are placed. If you provide a directory name that does not exist, Doxygen creates a directory with the appropriate user rights under that name.

　　<INPUT> : This tag creates a list of all directories separated by spaces, which contains the C/C++ source code files and header files that need to be generated by the document. For example, consider the following code snippet:

INPUT =/home/user1/project/kernel/home/user1/project/memory

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

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

　　<RECURSIVE> : If the source code hierarchy is nested and you need to generate documents for files on all levels C/C++ , 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 and other subdirectories. If this tag is set to Yes,Doxygen will recursively search the entire hierarchy and extract the information.

　　<EXTRACT_ALL> : This tag tells Doxygen to extract information even if the classes or functions do not have documents. This token 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.

(2) Document output format　　

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

UNIX manual page: <GENERATE_MAN> Set the tag to Yes. By default, the man subfolder is <OUTPUT_DIRECTORY> created in the specified directory , and the resulting document is placed in this folder. This folder must be added to the MANPATH environment variable.

Rich Text Format (RTF): <GENERATE_RTF> Sets the tag to Yes. <RTF_OUTPUT>set the tag to the directory where you want to place the. rtf file; By default, the document is placed in the RTF subfolder in Output_directory. To support cross-document browsing, you should <RTF_HYPERLINKS> set the tag to Yes. If this flag is set, the generated. rtf file will contain cross-document links.

latex: By default, Doxygen generates Latex and HTML-formatted documents. In the default doxyfile, the <GENERATE_LATEX> tag is set to Yes. In addition, the <LATEX_OUTPUT> tag is set to Latex, which means that a latex subfolder is created in output_directory and a latex file is generated in it.

microsoft®compiled HTML Help (CHM) format: <GENERATE_HTMLHELP> set the tag to Yes. Because this format is not supported on UNIX platforms, Doxygen only generates a index.hhp file in the folder where the HTML file is saved. You must convert this file to a. chm file through the HTML help compiler.

Extensible Markup Language (XML) format: <GENERATE_XML> set the tag to Yes. (Note that the Doxygen development team is also developing XML output.)

(3) graphics and icon generation

By default, Doxyfile <CLASS_DIAGRAMS> sets the tag to Yes. This tag is used to generate a class hierarchy diagram. To generate a better view, you can download the dot tool from the Graphviz download site. The following tags in doxyfile are used to generate the chart:

　　<CLASS_DIAGRAMS> : This flag is set to Yesby default in Doxyfile. If this tag is set to no, an inheritance hierarchy chart is not generated.

　　<HAVE_DOT> : If this tag is set to Yes, Doxygen uses the dot tool to generate more powerful graphics, such as collaboration diagrams that help understand class members and their data structures. Note that if this tag is set to Yes, the <CLASS_DIAGRAMS> tag is invalid.

　　<CLASS_GRAPH> : if the <HAVE_DOT> tag and this tag are set to Yesat the same time, the dot build inheritance hierarchy chart is used, and its appearance is richer than when it is used only <CLASS_DIAGRAMS> .

　　<COLLABORATION_GRAPH> : if the <HAVE_DOT> tag and this tag are set to Yesat the same time, Doxygen will generate a collaboration diagram (as well as an inheritance graph) that shows the individual class members (i.e. included) and their subsequent

Hierarchical structure.

(4) Code document style

Each code element is described in two ways: short and detailed. A short description is usually a single line. Functions and class methods also have a third description of the body description (in-body description), which sets together all the comment blocks found in the function body. Some of the more commonly used Doxygen tags and annotation styles are as follows:

• Short Description: use a single-line C++ comment, or use a <\brief> tag.
• Detailed Description: use JAVADOC-style annotations /** … test … */ (note the first two asterisks [ * ]) or Qt-style annotations /*! … text … */ .
• In Vivo Description: elements such as classes, structures, unions, and namespaces C++ all have their own tags, such as,, <\class> <\struct> , <\union> and <\namespace> .

In order to generate documents for global functions, variables, and enumeration types, you must first use tags for the corresponding files <\file> . The example shown in Listing 12 contains markup for four elements: a function tag ( <\fn> ), a function parameter marker (), <\param> a variable name tag ( <\var> ), a tag used for #define (), and a <\def> tag that represents an issue related to a code fragment ( <\warning> ）。

Here are some Doxygen self-built commands that you can add to your code comments

@addtogroup added to a group.
@brief    profile
@deprecated   deprecated function
@details   detailed description
@note    start a paragraph to describe some considerations
@par    start a paragraph, The paragraph name description is specified by yourself
@param   
@code: @ Endcode 
@fn    function description
@ingroup   join to a group
@return   　　 description return meaning
@retval    description return value meaning
@include   include file

3. Other

　　Doxygen functionality is also very powerful, for C + + and Java code structure generation and icon generation is very useful, you can easily see the code structure, for C temporarily did not generate a corresponding chart, the follow-up need to continue to study. Subsequent get to other skills continue to be added later

Doxygen Generating Source Documents