Introduction to doxygen

What is doxygen?

Doxygen is a program file generation tool that converts a specific annotation in the program into a description file.

We usually write comments more or less when writing a program, but for others, we need to directly explore the comments in the program, just as hard as salvage the titani. Most of the useful comments are for functions, classes, and so on. Therefore, if you can reorganize the annotation into a pure reference manual based on the program structure, it will reduce the burden for people who will use your program code later. On the other hand, File Sorting is a heavy burden for you.

For Unarchived source files, you can also configure doxygen to extract the code structure. Alternatively, you can use the automatically generated dependency graph (including dedependency graphs), inheritance graph (inheritance divisor), and collaborationdivisor to visualize the relationships between documents. The formats of help documents generated by doxygen can be CHM, RTF, postscript, PDF, HTML, and unixmanpage.

A good programmer adds appropriate comments to appropriate places when writing a program. If you are able to slightly conform to a certain format when writing comments, then you can use a tool program to generate beautiful tokens Based on the program structure and your annotations. This will give many programmers time to have more coffee.

Doxygen is such a tool. When you write comments, follow the rules you have developed. Then, he will be able to help you generate a beautiful pipeline. Therefore, the use of doxygen can be divided into two parts.The first is to write the annotation in a specific format, and the second is to use the doxygen tool to generate the annotation.

Currently, doxygen can process the following programming languages:

• C/C ++
• Java
• IDL (CORBA, Microsoft and KDE-DCOP type)

The following formats can be generated:

• Html
• XML
• Latex
• RTF
• UNIX man page

In addition, many other formats can be derived. If you have latex files, you can use some tools to generate ps or PDF files.

Doxygen currently supports 2 to 30 languages. Since doxygen 1.2.16, traditional Chinese is supported (this is a good thing the younger brother has done ). Therefore, in some open source program file generators, doxygen is a complete set. In terms of program language processing, doxygen is also one of the few tools that can work normally under Borland C ++ builder syntax (if not, the younger brother will not recommend it ).

The purpose of this article is to give you an overview after carefully reading this article. So that you can easily use doxygen. For details about how to use doxygen, refer to the sequence attached with doxygen. In fact, doxygen's own user manual is generated using doxygen. You can see that he can actually generate a file that is far more complex than the reference book.

 

Install doxygen

The installation of doxygen is very simple. This article only describes the installation of binary files. If you are interested in re-Compile from source code, please refer to the reference manual.

First, capture the latest doxygen version on the website of doxygen. Currently, as long as you are Linux, Solaris, Mac OS X, HP-UX, or even unixware, there are compile binary versions that can be crawled. If it is Windows 95/98/ME/NT/2000/XP, or even the setup version, you can capture it. Therefore, the installation process is very simple. As long as the correct installation directory is provided, I believe that there will be no problems in installation.

In addition, if you are using Linux or windows, you can also crawl the doxygen Wizard program. This is an auxiliary tool that helps you quickly create a doxygen configuration file. With this configuration file, you can quickly generate a token. In addition, if the doxygen wizard is not used, you can still use a general text editor to create the Configuration Wizard.

If the installation is successful, you can see that the doxygen execution file appears in your system. If it is a Windows platform, you can see that there is a folder named doxygen in the Assembly.

 

Configure doxygen for a project

Doxygen generates tokens that can be dividedThree steps. One is to create a configuration file for the project, and the other is to add the annotation format defined by doxygen in the program code. Third, use doxygen to generate comments.

Therefore, the first step is to create a doxygen configuration file for your project. The format of this so-called configuration file is actually very simple. Is the key and value settings. Set each row to one. If the first line starts with "#", this behavior annotation is used. Doxygen ignores it. The format of each row is as follows:

Tag = value [value,...]

And

Tag + = value [value,...]

The first form is the most common, that is, to set a tag (that is, a key), and its value is the part defined on the right. In principle, each value is a single English text. If the value you want to define contains a space character, you can use double quotation marks to enclose it. If you want to define more than one value, use commas (,) to separate them.

If the tag you want to define belongs to the table column type, many values are separated by commas. In the doxygen configuration example, you can repeatedly define it in different places. Only the following definition should use the second form mentioned above. In this form, the values of the two definitions are merged.

After knowing the basic format, the rest is to set according to the meaning of each tag. There are many tag definitions. Here we only describe the tags that are necessary. For the rest, read the instructions on your own.

Because doxygen still has a lot of tags, to facilitate use, doxygen itself provides a convenient option, you can create a blank doxygen file (doxygen is the default configuration token name of doxygen ).

> Doxygen

With this command, you can get a doxygen file, and then you can use a general text editor to edit it.

The following describes several necessary tags:

Project_name	The name of a project, mainly one word. Enclose multiple words in double quotation marks.
Project_version	The version number of the project.
Output_directory	Output path. The generated file will be placed under this path. If this path is not specified, the current path is used as the output path.
Output_language	Output language. The default value is English. After version 1.2.16, you can use Chinese-traditional to output the traditional Chinese format.
Input	Specifies the path for loading or searching for the program code file to be processed. Here is a table column type. You can also specify the file and path. For example, if you have three files, A. C, B. C, and C. C. You can use input = A. C, B. C, and C. C. If you specify a directory, all files under the directory will be processed.
File_patterns	If the directory is specified in your input tag. You can use this tag to request that doxygen only perform actions on specific files during processing. For example, you want to process files with the extension. C,. cpp, And. h in the directory. You can set file_patterns = *. C, *. cpp, *. h.
Recursive	This is a Boolean tag and only accept yes or no. When set to yes, all subdirectories in the directory specified by input will be processed.
Exclude	If you have several specific files or directories, you do not want them to be processed by doxygen. You can specify in this tag.
Exclude_patterns	Similar to file_patterns, this tag is used for exclude.
Source_browser	If yes, doxygen generates a list of source files for reference.
Inline_sources	If set to yes, the program code will also be embedded in the description file.
Alphabetical_index	If it is set to yes, a alphabetical list will be added to the generated file.
Generate_html	If it is set to yes, the html version of the description is generated. HTML encoding is one of the formats preset by doxygen.
Html_output	HTML file output directory. This is a relative path, so the actual path is output_directory with html_output. The default setting is HTML.
Html_file_extension	The extension of the HTML file. Set it to .html.
Html_header	Use the header in the HTML response of each page. If not specified, doxygen uses its own preset header.
Html_footer	The footer to be used in the HTML layout of each page. If not specified, doxygen uses its own preset footer.
Html_stylesheet	You can give a CSS setting to make the HTML output result more perfect.
Generate_htmlhelp	If yes is set, doxygen will generate an index file. This index file is used when you need to create an HTML Help file on Windows.
Generate_treeview	If it is set to yes, doxygen will help you generate a tree structure, on the left side of the screen. The tree structure is written in JavaScript. Therefore, the new version of browser is required to be correctly displayed.
Treeview_width	Used to set the width of the tree structure on the screen.
Generate_latex	If set to yes, latex files will be generated. However, you must have related tools to install latex in your system.
Latex_output	The output directory of the latex file, which is used in the same way as html_output, also refers to the path under output_directory. Default Value: latex.
Latex_1__name	The command name and file of the latex program. Default Value: latex.
Generate_rtf	If it is set to yes, a description in the RTF format is generated.
Rtf_output	Similar to html_output, it is used to specify the path of the RTF output file. Default Value: RTF.
Generate_man	If set to yes, a Unix man page format description is generated.
Man_output	Similar to html_output, it is used to specify the output directory of man page. The default value is man.
Generate_xml	If set to yes, a description in XML format is generated.
Enable_preprocessing	If it is set to yes, doxygen starts the C processor to process the original file.
Predefined	You can customize some macros. Similar to the-D option in GCC.

If the above basic tags are set correctly, the next step is to modify your source code annotation to the correct format. If you think it is very troublesome to use a general text editor to edit the configuration token, we recommend that you use the doxygen wizard tool. He can quickly construct the doxygen file you need.

 

Write comments in the correct format

Not all comments in program code are processed by doxygen. You must follow the correct format. In principle, doxygen only processes comments related to program structures, such as function, class, and archive comments. The internal comments of the function are not processed.

Doxygen can process the following types of annotations.

Javadoc type:

/**
*... Annotation...
*/

 

Qt type:

/*!
*... Annotation...
*/

Single Row Type annotation:

///... Annotation...

Or

//! ... Annotation...

 

The type you want to use depends on your preferences. For the author, I will use javadoc for a wide range of annotations. The single-row annotation uses the "//" type.

In addition, because doxygen is treated as the program code after the interpretation for the annotation. That is to say, any annotation is the program code after the annotation.

If you want to annotate the previous code, you need to annotate the Code in the following format.

/*! <... Annotation ...*/
/** <... Comment ...*/
//! <... Annotation...
/// <... Annotation...

The above method is not applicable anywhere and can only be used in the member of class or function parameters.

For example, if we have the following class.

Class myclass {
Public:
Int member1;
Int member2:
Void member_function ();
};

After the annotation is added, it becomes like this:
/**
* My custom class description...
*/
Class myclass {
Public:
Int member1; // <description of the first member...
Int member2: // <second member description...
Int member_function (int A, int B );
};

/**
* Description of custom class member_funtion...
*
* @ Param A description of parameter
* @ Param B Description of parameter B
*
* @ Return returns a + B.
*/
Int myclass: member_function (int A, int B)
{
Return A + B;
}

When you use doxygen to generate instructions, doxygen will parsing your code. Create the corresponding file according to the program structure. Then, place your comments in the correct place based on their locations.

You may have noticed that there are some other special commands, such as @ PARAM and @ return, in addition to general text instructions. This is another important part of doxygen, because a class or function has several fixed parts to be explained. In order for doxygen to be able to determine, all of us must use these commands to tell doxygen that the comments behind them are explaining something. During Processing, doxygen will help you specially process or typeset these parts. You can even create a reference hyperlink.

First, we first describe a specific format for class or function annotation in doxygen.

/**
* Simple description of class or function...
*
* Detailed description of class or function...
*...
*/

In the above example, when doxygen processes a class or function annotation, it first judges the first simple description of the behavior. This simple description will continue until a blank row appears. Or until the first "." is encountered.

Subsequent annotations will be considered as detailed descriptions. The difference between the two is that doxygen only displays simple instructions in some places, rather than detailed descriptions. For example, the list of classes or functions.

Another clear method is the @ brief command. This will clearly tell doxygen, which is a simple description. For example:

/**
* @ Brief description of the class or function...
*
* Detailed description of class or function...
*...
*/

In addition to this class and function, doxygen can also describe the file, provided that the annotation must be placed before the file. It mainly uses some commands, which are usually placed at the beginning of the file. For example:

/*! \ File myfile. h
\ Brief description of brief files

Detailed description.

\ Author information
*/

As you can see, the file annotation format is as follows: do not confuse it. In fact, both "\" and "@" are the same. They all tell doxygen that a command is followed. Both are available in doxygen. I prefer "@".

Next we will explain some common commands:

@ File	Description of the file.
@ Author	Author's Information
@ Brief	It is used for class or function comments, followed by a simple description of class or function.
@ Param	Format: @ Param arg_name parameter description It is mainly used in the function description, followed by the parameter name, and then followed by the description about this parameter.
@ Return	Returns the description of the function. Used in function annotation. Returns the result of the function.
@ Retval	Format: @ Retval value return value description It is mainly used in function description to explain the meaning of a specific return value. Therefore, a return value must be followed. Then, describe the returned value.

Doxygen supports many commands, and some even control the output layout. You can find detailed instructions in doxygen instructions.

Next we will prepare a set of example. h and example. cpp to describe how to use the doxygen annotation:

Example. h:

/**
* @ File the include file in this example.
*
* This file only defines the class example.
*
* @ Author garylee @ localhost
*/

# Define example_ OK 0 // <macro defining example_ OK is 0.

/**
* @ Brief example class brief description
*
* This example describes example class.
* This is an extremely simple example.
*
*/
Class Example {
PRIVATE:
Int var1; // <this is a private variable.
Public:
Int var2; // <this is a public variable member.
Int var3; // <this is another public variable member.
Void exfunc1 (void );
Int exfunc2 (int A, char B );
Char * exfunc3 (char * C );
};


Example. cpp:

/**
* @ File the program code file in this example.
*
* This file is used to define the class of example.
* Member function.
*
* @ Author garylee @ localhost
*/

/**
* @ Brief exfunc1 simple description
*
* Exfunc1 does not have any parameters or return values.
*/
Void example: exfunc1 (void)
{
// Empty funcion.
}

/**
* @ Brief exfunc2 simple description
*
* Exfunc3 () returns the sum of the two parameters.
*
* @ Param A refers to the parameter used for addition.
* @ Param B refers to the parameter used for addition.
* @ Return returns the result of adding two parameters.
*/
Int exfunc2 (int A, char B)
{
Return (A + B );
}

/**
* @ Brief exfunc3 simple description
*
* Exfunc3 () Only returns the metric input by the parameter.
*
* @ Param C refers to the character pointer passed in.
* @ Retval null Null String.
* @ Retval! Null is a non-null string.
*/
Char * exfunc2 (char * C)
{
Return C;
}

The above two files briefly explain how to use the doxygen annotation. You can add corresponding comments to your program code according to this principle.

In fact, whether or not you use doxygen, you may want to write the annotation in his format. On the one hand, it does not interfere with the operation of your program. On the other hand, doxygen defines what the basic program annotation should need. Writing clear comments is what a good programmer should do.

 

Create instruction file

After all the preceding steps are correctly executed, you only need to execute the following command to create the file you want:

> Doxygen

If an error occurs, check whether your doxygen configuration token settings are correct and whether the directory access permission is sufficient. If the output result is incorrect, check whether your annotation meets the format. The location of the annotation is correct. For example, you cannot insert other program code or declaration into the annotation of the class and the class itself. Otherwise, doxygen cannot match the Annotation with the class.

If you use doxygen wizard, you can directly use the run button or the menu item above to create a description file. For example, in html##, the index.html in the directory specified by html_outputwill be the homepage of your description file.

Currently, in traditional Chinese, only HTML and RTF format descriptions are successfully produced. The process of other formats is complex. You need to use other tools.

 

FAQs:

1: How can I support Chinese characters? (The Chinese comments in the default code are garbled characters)
Modify Step2-Expert labels-Input-INPUT_ENCODING = cp936

2: how to generate CHM?
Modify Step2-Expert labels-HTML-CHM_FILE = D:/yours. CHM
Hhc_location = C:/program files/HTML Help Workshop/hhc.exe

Appendix: writing comments

How to write comments, write more or write less. Too many comments may even interfere with code reading. One general principle of writing comments is that comments should be used to indicate the author's intention, at least to summarize some code, rather than repeating or interpreting the code. The code that repeats or explains the code may be easier to understand. It reflects the purpose of the author's intention to interpret the code by commenting on the problem-solving level, while the Code summative comments are comments at the question-answering level.

The recommended process of writing comments is to first use comments to outline the main framework of the code, and then write the corresponding code according to the comments. Comment out the main data structures, output functions, and variables common to multiple functions in detail. Comments the control structure and single-purpose statement set in the code. The following are some important points to note when writing comments:

 

Avoid comments on separate statements;

By commenting on why, or what to do, the code reader can only read and understand the code;

Comment on areas where readers may have doubts;

Comment on the data definition, rather than the usage process;

Rewrite codes that are hard to understand, instead of trying to explain them through annotations;

Comment out key control structures;

Comment on data and function boundaries and usage premises;