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

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

https://blog.csdn.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.csdn.net/czyt1988/article/details/21743595

 

 

阅读更多 登录后自动展开
想对作者说点什么? 我来说一句

没有更多推荐了,返回首页