C ++ standard annotation principle-C ++ annotation Based on doxygen

Remark Overview

When downloading source code outside China, you can often see the accompanying instructions and detailed instructions. Most documents can be generated using the cross-platform software doxygen, doxygen cannot read your c ++ comments at will and must follow certain rules to generate them. Therefore, when writing code, you must write comments according to the standard, otherwise, it will cause a lot of trouble in the future.

The following describes how to mark C ++. c ++ does not recommend C-language/**/style annotations. Here, except for the file header, C ++-style annotations are used.

Let's take a look at the summary:

File Header:

/*! * \ File ctext. H * \ brief overview ** detailed overview ** \ author name * \ version Version Number (Maj. min, main version. version by version) * \ date */

Namespace:

/// \ Brief introduction to the brief namespace ///// detailed description of the namespace text {......}

Class description:

/// \ Brief ctext doxygen test ///// class ctext for doxygen test {}

Function Annotation
Method 1:

/// \ Brief Function brief description-test function // \ Param N1 parameter 1 // \ Param C2 parameter 2 // \ return description bool text (INT N1, ctext C2 );

Method 2:

//// Brief description of the \ brief function-Detailed description of the test function //// function. Here, the detailed description of the function can be written, which can be a line break ///, as shown here, at the same time, you must note that there must be a blank line between the description and brief description ///, no identifier // \ Param N1 parameter 1 Description // \ Param C2 parameter 2 Description // \ return description // \ See text bool text2 (INT N1, ctext C2 );

Variables and enumeration
 

Int M_a; // <The member variable 1m_a indicates double m_ B; /// <member variable 2m_ B description /// \ brief member variable M_c brief description // a detailed description of member variable M_c, here we can describe the variables in detail. The specific method and function annotation are the same as float M_c; /// \ brief XXX Brief description of the enumerated variables ///// XXX detailed description of the enumerated variables -- a detailed description of the enumerated variables and a detailed description of the functions /// write is consistent. Each enumerated variable can separately describe Enum {em_1, /// <description of enumeration value 1 em_2, /// <description of enumeration value 2 em_3 // <description of enumeration value 3 };

1. File Header description

The file header description is written in the following format:

/*! * \ File ctext. H * \ brief overview ** detailed overview ** \ author, including email and other * \ version versions (Maj. min, main version. version by version) * \ date */

And so on.

/*! \ File ctext. h \ brief overview \ author, including email and other \ version versions (maj. Min, main version. version by version format) \ date */

For vs compiler, the line * in the middle may be troublesome. You can leave it empty. For QT, the line * in the middle should be removed, but it is not necessary to remove it if it is troublesome.
Use doxygen to generate the following comments:

2. namespace

The namespace description is as follows:

/// \ Brief introduction to the brief namespace ///// detailed description of the namespace text {}

The description of doxygen is similar

/// \brief/// /// 

We will see a lot of such statements below
The following figure shows the effect of doxygen.

3. Class description

Class comments are the same as functions,

/// \ Brief ctext doxygen test ///// class ctext for doxygen test {}

The effect of using doxygen to generate a document is as follows:

4. Function annotation principles

Function detailed comments are stored in the header file. The CPP file only provides concise comments for functions.
The CPP file does not contain // comments. Otherwise, it overlaps with the header file.

4.1 Brief description of functions

Annotation Method 1:

/// \ Brief Function brief description-test function // \ Param N1 parameter 1 // \ Param C2 parameter 2 // \ return description bool text (INT N1, ctext C2 );

Brief Comment this comment will let doxygen generate a Function brief description and parameter description
The generated result is as follows:

4.2 Brief description of functions + detailed description

//// Brief description of the \ brief function-Detailed description of the test function //// function. Here, the detailed description of the function can be written, which can be a line break ///, as shown here, at the same time, you must note that there must be a blank line between the description and brief description ///, no identifier // \ Param N1 parameter 1 Description // \ Param C2 parameter 2 Description // \ return description bool text2 (INT N1, ctext C2 );

The effect of using doxygen to generate a document is as follows:

4.3 function annotation without a brief description

/// Function description-test function // detailed description of the function. Here, the detailed description of the function is written. The description can be wrap. //, as shown here, at the same time, you must note that there must be a blank line between the description and brief description ///, no identifier // \ Param N1 parameter 1 Description // \ Param C2 parameter 2 Description // \ return description bool text3 (INT N1, ctext C2 );

The effect of using doxygen to generate a document is as follows:

Not described here

4.4 refer to the Writing Method

/// \ Brief function description-test function 4 // \ Param N1 parameter 1 Description /// \ Param C2 parameter 2 Description /// \ return description ///\ see text3 text2 text bool text4 (INT N1, ctext C2 );

The effect of using doxygen to generate a document is as follows:



\ See can contain Chinese characters and other instructions. doxygen automatically recognizes functions in the code.

5. Variable comments

Variable comments are described with // <. For detailed information, add \ brief

Int M_a; // <The member variable 1m_a indicates double m_ B; /// <member variable 2m_ B description /// \ brief member variable M_c brief description // a detailed description of member variable M_c, here we can describe the variables in detail. The specific method and function annotation are the same as float M_c;

If the variables need to be described in detail, they can already be written in M_c format,Note that there must be a blank line between m_ B and M_c.Otherwise, the description of m_ B disappears.
The specific effect of using doxygen to generate a document is as follows:

6. Enumeration

The annotation of enumerated variables is as follows:

/// \ Brief XXX Brief description of the enumerated variables ///// XXX detailed description of the enumerated variables -- a detailed description of the enumerated variables and a detailed description of the functions /// write is consistent. Each enumerated variable can separately describe Enum {em_1, /// <description of enumeration value 1 em_2, /// <description of enumeration value 2 em_3 // <description of enumeration value 3 };

The general description of enumeration is the same as that of the function. The description of each enumeration variable is the same as that of the variable.
The effect of using doxygen to generate the above annotation is as follows:

7. doxygen settings and Chinese problems

7.1 generate private members

If you want to generate a private member (doxygen does not generate a private member by default), you can set
Select the build item of the "expert" tab and check "extract_private ".

7.2 Chinese problems

Chinese characters are sometimes garbled
For vs2010 documents, the default value is gb2312. You can set
Doxyfile_encoding of the project under the expert tag is gb18030
Input_encoding: gb18030

In addition, set output_language to Chinese.

For other code files if Chinese garbled, you can use a text editor to convert the code text encoding to a UTF-8 with BOM (note that this may affect the code, so back up the conversion code ), and then export.

8. Quick tagging for vs2008, vs2010, and later ides

Compilers such as vs2010 cannot generate the above annotation style like QT creator, but can be integrated into the toolbar of vs. The integration method is shown in:

In this way, you can drag the label directly from the toolbox, which is very convenient.

Appendix:

Ctext. h

/*! * \ File ctext. H * \ brief overview ** detailed overview ** \ author, including email and other * \ version versions (Maj. min, main version. version format) * \ date */# pragma once // \ brief introduction to the namespace text {}/// \ brief ctext doxygen test ///// class ctext {public: ctext (void );~ Ctext (void ); /// \ brief Function brief description-test function // \ Param N1 parameter 1 Description // \ Param C2 parameter 2 Description // \ return description bool text (int n1, ctext C2); // Brief description of the \ brief function-test function // detailed description of the function. Here, the detailed description of the function can be written, with a line break ///, as shown here, you must also note that there must be a blank line between the detailed description and the brief description ///, no identifier // \ Param N1 parameter 1 Description // \ Param C2 parameter 2 Description // \ return description bool text2 (INT N1, ctext C2); // function description-test function // function description. Here, the detailed description of the function can be written, which can be a line break ///, as shown here, note that the description is required between the description and brief description. A blank line ///, no identifier // \ Param N1 parameter 1 Description // \ Param C2 parameter 2 Description // \ return description bool text3 (INT N1, ctext C2 ); /// \ brief function description-test function 4 // \ Param N1 parameter 1 Description /// \ Param C2 parameter 2 Description /// \ return description ///\ see text3 text2 text bool text4 (INT N1, ctext C2); int M_a; // <The member variable 1m_a indicates double m_ B; /// <member variable 2m_ B description /// \ brief member variable M_c brief description // a detailed description of member variable M_c, the variables can be described and described in detail. The specific method and function annotation are the same as float M_c; // \ brief A brief description of the XXX enumerated variables //// a detailed description of the XXX enumerated variables -- a detailed description of the enumerated variables and a detailed description of the functions /// are written in the same way. Each enumerated variable can separately describe Enum {em_1, /// <description of enumeration value 1 em_2, /// <description of enumeration value 2 em_3 // <description of enumeration value 3 };};