C++标准注释原则 - 基于doxygen的C++注释

https://blog.****.net/czyt1988/article/details/8901191

 

标注总述

下载国外的源代码，往往能看到附带的说明文档，文档都有详细的说明，大部分文档都可以通过doxygen这个跨平台软件生成，doxygen并不能随便读取你的C++的注释,必须按照一定的规则才能生成，所以在编写代码时，一定要按照标准写注释，否则会为以后带来许多麻烦

下面介绍C++的标注写法，c++不推荐c语言式的/* */风格注释，这里，除了文件头使用这种注释外其余到使用C++风格的注释。

先看看总述：

 

文件头：

 

[cpp] view plain copy

1. <code class="language-cpp">/*! 
2. * \file Ctext.h 
3. * \brief 概述  
4. *  
5. *详细概述  
6. *  
7. * \author 作者名字 
8. * \version 版本号(maj.min，主版本.分版本格式)  
9. * \date 日期  
10. */  
11. </code>  

 

 

 

命名空间：

1. /// \brief 命名空间的简单概述

2. ///

3. ///命名空间的详细概述

4. namespace text

5. {

6. ……

7. }

类说明：

1. /// \brief Ctext的doxygen测试

2. ///

3. /// 作doxygen测试用

4. class Ctext

5. {

6. }

函数标注
   方法1：

1. /// \brief 函数简要说明-测试函数

2. /// \param n1 参数1

3. /// \param c2 参数2

4. /// \return 返回说明

5. bool text(int n1,Ctext c2);

   方法2：

1. /// \brief 函数简要说明-测试函数

2. ///

3. /// 函数详细说明，这里写函数的详细说明信息，说明可以换行

4. /// ，如这里所示，同时需要注意的是详细说明和简要说明之间必须空一行

5. /// ，详细说明之前不需要任何标识符

6. /// \param n1 参数1说明

7. /// \param c2 参数2说明

8. /// \return 返回说明

9. /// \see text

10. bool text2(int n1,Ctext c2);

变量及枚举

1. int m_a; ///< 成员变量1m_a说明

2. double m_b; ///< 成员变量2m_b说明

3.  
4.  

5. /// \brief 成员变量m_c简要说明

6. ///

7. /// 成员变量m_c的详细说明，这里可以对变量进行

8. ///详细的说明和描述，具体方法和函数的标注是一样的

9. float m_c;

10.  
11.  

12. /// \brief xxx枚举变量的简要说明

13. ///

14. /// xxx枚举变量的详细说明--枚举变量的详细说明和函数的详细说明

15. ///的写法是一致的。每个枚举变量下可以进行单独说明

16. enum{

17. em_1,///< 枚举值1的说明

18. em_2,///< 枚举值2的说明

19. em_3 ///< 枚举值3的说明

20. };

 

1.文件头说明

文件头说明按照如下格式写

1. /*!

2. * \file Ctext.h

3. * \brief 概述

4. *

5. *详细概述

6. *

7. * \author 作者,包含email等

8. * \version 版本号(maj.min，主版本.分版本格式)

9. * \date 日期

10. */

上注释等下于下面这种写法

1. /*!

2. \file Ctext.h

3. \brief 概述

4. 详细概述

5. \author 作者,包含email等

6. \version 版本号(maj.min，主版本.分版本格式)

7. \date 日期

8. */

对于vs编译器可能中间那行*号比较麻烦，可以不写，对于Qt这种要去掉中间的*号反而是件麻烦事就不用去掉
用doxygen生成注释如下效果

 

 

2. 命名空间

 

命名空间说明如下写

1. /// \brief 命名空间的简单概述

2. ///

3. ///命名空间的详细概述

4. namespace text

5. {

6.  

7. }

doxygen的说明写法都是类似于

1. /// \brief

2. ///

3. ///

以下将会见到很多这样的写法
上注释的doxygen效果如下

3. 类说明

类的注释和函数一样，

1. /// \brief Ctext的doxygen测试

2. ///

3. /// 作doxygen测试用

4. class Ctext

5. {

6. }

上注释用doxygen生成文档效果如下：

 

 

4.函数注释原则

 

函数详细注释位于头文件，cpp文件只对函数做简明注释
cpp文件不做///的注释，否则会和头文件重叠

4.1 函数简要说明

注释方法1：

1. /// \brief 函数简要说明-测试函数

2. /// \param n1 参数1

3. /// \param c2 参数2

4. /// \return 返回说明

5. bool text(int n1,Ctext c2);

简要注释此注释会让doxygen生成函数简要说明和参数说明
生成结果如：

4.2 函数简要说明+详细说明

 

1. /// \brief 函数简要说明-测试函数

2. ///

3. /// 函数详细说明，这里写函数的详细说明信息，说明可以换行

4. /// ，如这里所示，同时需要注意的是详细说明和简要说明之间必须空一行

5. /// ，详细说明之前不需要任何标识符

6. /// \param n1 参数1说明

7. /// \param c2 参数2说明

8. /// \return 返回说明

9. bool text2(int n1,Ctext c2);

上注释用doxygen生成文档效果如下：

 

4.3 不带简要说明的函数标注

1. /// 函数说明-测试函数

2. ///

3. /// 函数详细说明，这里写函数的详细说明信息，说明可以换行

4. /// ，如这里所示，同时需要注意的是详细说明和简要说明之间必须空一行

5. /// ，详细说明之前不需要任何标识符

6. /// \param n1 参数1说明

7. /// \param c2 参数2说明

8. /// \return 返回说明

9. bool text3(int n1,Ctext c2);

上注释用doxygen生成文档效果如下：

这里没有说明

 

4.4 带参见的写法

1. /// \brief 函数说明-测试函数4

2. /// \param n1 参数1说明

3. /// \param c2 参数2说明

4. /// \return 返回说明

5. /// \see text3 text2 text

6. bool text4(int n1,Ctext c2);

上注释用doxygen生成文档效果如下：



\see 上可以带中文等说明，doxygen会自动识别代码里存在的函数

5.变量注释

变量注释用///< 对变量进行说明，对于详细信息可以加\brief
  

1. int m_a; ///< 成员变量1m_a说明

2. double m_b; ///< 成员变量2m_b说明

3.  

4. /// \brief 成员变量m_c简要说明

5. ///

6. /// 成员变量m_c的详细说明，这里可以对变量进行

7. ///详细的说明和描述，具体方法和函数的标注是一样的

8. float m_c;

如果变量需要详细说明的可已按照m_c的写法写，注意，m_b和m_c之间一定需要空行，否则会导致m_b的简述消失
上注释用doxygen生成文档的具体效果如下



 

6.枚举

枚举变量的标注方法如下

1. /// \brief xxx枚举变量的简要说明

2. ///

3. /// xxx枚举变量的详细说明--枚举变量的详细说明和函数的详细说明

4. ///的写法是一致的。每个枚举变量下可以进行单独说明

5. enum{

6. em_1,///< 枚举值1的说明

7. em_2,///< 枚举值2的说明

8. em_3 ///< 枚举值3的说明

9. };

枚举的总体说明和函数的写法一致，每个枚举变量的说明和变量的说明写法一致
上注释用doxygen生成效果如下：

 

 

7.doxygen的设置和中文问题

 

7.1 生成私有成员

如果想生成私有成员（doxygen默认不生成私有成员），可以如下设置
选择Expert标签的Build项，勾选EXTRACT_PRIVATE即可

7.2 中文问题

中文有时候是乱码
对于vs2010的文档，默认是gb2312，可以设置
Expert标签的Project项目的DOXYFILE_ENCODING 为 GB18030
INPUT_ENCODING 为 GB18030

另外Project项目的生成语言（OUTPUT_LANGUAGE）选择Chinese

 

对于其他的代码文件如果中文乱码，可以用文本编辑器转换代码文本编码为UTF-8带BOM的（注意这有可能影响代码，所以转换编码时要备份），再进行导出。

 

 

 

 

8.vs2008、vs2010 及以上IDE的快速标注方法

 

vs2010 等编译器并不能像Qt Creator那样生成上述标注样式，但是可以集成到vs的工具栏里，集成方法如下图所示：

这样在标注时可以直接从工具箱拖曳了，非常方便

 

 

附：

Ctext.h

 

 

1. /*!

2. * \file Ctext.h

3. * \brief 概述

4. *

5. *详细概述

6. *

7. * \author 作者,包含email等

8. * \version 版本号(maj.min，主版本.分版本格式)

9. * \date 日期

10. */

11.  

12. #pragma once

13. /// \brief 命名空间的简单概述

14. ///

15. ///命名空间的详细概述

16. namespace text

17. {

18.  

19. }

20.  

21. /// \brief Ctext的doxygen测试

22. ///

23. /// 作doxygen测试用

24. class Ctext

25. {

26. public:

27. Ctext(void);

28. ~Ctext(void);

29. /// \brief 函数简要说明-测试函数

30. /// \param n1 参数1说明

31. /// \param c2 参数2说明

32. /// \return 返回说明

33. bool text(int n1,Ctext c2);

34. /// \brief 函数简要说明-测试函数

35. ///

36. /// 函数详细说明，这里写函数的详细说明信息，说明可以换行

37. /// ，如这里所示，同时需要注意的是详细说明和简要说明之间必须空一行

38. /// ，详细说明之前不需要任何标识符

39. /// \param n1 参数1说明

40. /// \param c2 参数2说明

41. /// \return 返回说明

42. bool text2(int n1,Ctext c2);

43. /// 函数说明-测试函数

44. ///

45. /// 函数详细说明，这里写函数的详细说明信息，说明可以换行

46. /// ，如这里所示，同时需要注意的是详细说明和简要说明之间必须空一行

47. /// ，详细说明之前不需要任何标识符

48. /// \param n1 参数1说明

49. /// \param c2 参数2说明

50. /// \return 返回说明

51. bool text3(int n1,Ctext c2);

52. /// \brief 函数说明-测试函数4

53. /// \param n1 参数1说明

54. /// \param c2 参数2说明

55. /// \return 返回说明

56. /// \see text3 text2 text

57. bool text4(int n1,Ctext c2);

58.  

59. int m_a; ///< 成员变量1m_a说明

60. double m_b; ///< 成员变量2m_b说明

61.  

62. /// \brief 成员变量m_c简要说明

63. ///

64. /// 成员变量m_c的详细说明，这里可以对变量进行

65. ///详细的说明和描述，具体方法和函数的标注是一样的

66. float m_c;

67.  

68. /// \brief xxx枚举变量的简要说明

69. ///

70. /// xxx枚举变量的详细说明--枚举变量的详细说明和函数的详细说明

71. ///的写法是一致的。每个枚举变量下可以进行单独说明

72. enum{

73. em_1,///< 枚举值1的说明

74. em_2,///< 枚举值2的说明

75. em_3 ///< 枚举值3的说明

76. };

77. };

 

 

另外可看看这篇文章里面的注释：http://blog.****.net/czyt1988/article/details/21743595