AI 助理
备案控制台
开发者社区 开发与运维 文章 正文

Doxygen详细介绍（三）（Doxygen注释风格）

2017-11-27 5269
版权
版权声明：
本文内容由阿里云实名注册用户自发贡献，版权归原作者所有，阿里云开发者社区不拥有其著作权，亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容，填写 侵权投诉表单进行举报，一经查实，本社区将立刻删除涉嫌侵权内容。
简介：

5      Doxygen的注释风格

5.1   综述

在每个代码项中都可以有两类描述, 这两类描述将在文档中格式化在一起: 一种就是brief描述, 另一种就是detailed。两种都是可选的，但不能同时没有。
顾名思义, 简述(brief)就是在一行内简述地描述。而详细描述(detailed description)则提供更长, 更详细的文档。
Doxygen支持c风格注释、c++风格注释以及javaDoc风格注释等，下面将分别予以介绍。
若需要通过Doxygen生成漂亮的文档，一般有如下几个地方需要使用Doxygen支持的风格进行注释：
    1） 文件头（包括.h和.cpp）
        主要用于声明版权，描述本文件实现的功能，以及文件版本信息等
    2） 类的定义
        主要用于描述该类的功能，同时也可以包含使用方法或者注意事项的简要描述
    3） 类的成员变量定义
        在类的成员变量上方，对该成员变量进行简要地描述
    4） 类的成员函数定义
        在类定义的成员函数上方，对该成员函数功能进行简要描述
    5） 函数的实现在函数的实现代码处，详细描述函数的功能、参数的含义、返回值的含义、使用本函数需要注意的问题、本函数使用其他类或函数的说明等
 

5.2    Doxygen支持的指令

5.2.1   概述

可以在注释中加一些Doxygen支持的指令，主要作用是控制输出文档的排版格式，使用这些指令时需要在前面加上“\”或者“@”（JavaDoc风格）符号，告诉Doxygen这些是一些特殊的指令，通过加入这些指令以及配备相应的文字，可以生成更加丰富的文档，下面对比较常用的指令做一下简单介绍。

5.2.2   常用指令介绍

@file
档案的批注说明。
@author
作者的信息
@brief
用于class 或function的简易说明
eg ：
@brief  本函数负责打印错误信息串
@param
主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明
@return
描述该函数的返回值情况
eg:
@return  本函数返回执行结果，若成功则返回TRUE，否则返回FLASE
@retval
描述 返回值类型
eg:
@retval NULL  空字符串。
@retval !NULL  非空字符串。
@ note
注解
@attention
注意
@ warning
警告信息
@enum
引用了某个枚举，Doxygen会在该枚举处产生一个链接
eg ：
@enum CTest::MyEnum
@var
引用了某个变量，Doxygen会在该枚举处产生一个链接
eg ：
@var CTest::m_FileKey
@class
引用某个类，
格式：@class <name> [<header-file>] [<header-name>]
eg:
@class CTest "inc/class.h"
@exception
可能产生的异常描述
eg:
@exception  本函数执行可能会产生超出范围的异常
 

5.3      JavaDoc风格的注释

5.3.1    概述

JavaDoc 风格的注释风格主要使用下面这种样式： 即在注释块开始使用两个星号 ‘ * ‘
  

   
   
    

    
    
  1. /**   description      
    2. 

    
    
  2.  *    description      
    3. 

    
    
  3.  *    description      
    4. 

    
    
  4.  */ 
    

    5.

5.3.2    简述与详述的方式

Doxygen 支持的块（类、函数、结构体等）的注释描述分为两种：简述  和  详述
一般注释的描述由简述开始，经过特殊分隔方式后，后面紧跟详述的内容， javaDoc 风格可以使用的分隔方法有以下两种：
1）        使用  \brief  参数标识，空行作为简述和详述的间隔标识 

 
 
    

  
  
  1. /*!    @brief  Brief description.  
    2. 

  
  
  2.  *    description continued.  
    3. 

  
  
  3.  *  
    4. 

  
  
  4.  *    Detailed description starts here.  
    5. 

  
  
  5.  */ 
    6.

2） 直接使用javaDoc风格，javaDoc风格自动以简述开头，以空行（或者小数点加空格）作为简述与详述的分割


   
   
    

    
    
  1. /**    Brief description  
    2. 

    
    
  2.  *    description continued  
    3. 

    
    
  3.  *  
    4. 

    
    
  4.  *    Detailed description starts here.  
    5. 

    
    
  5.  */ 
    6. 
   
   



 
 
    

  
  
  1.  
    2. 

  
  
  2. /**        Brief description  
    3. 

  
  
  3.  *         description continued . (注意:这里有一个小数点,加上一个空格)  
    4. 

  
  
  4.  *         Detailed description starts here.  
    5. 

  
  
  5.  */ 
    6.

5.3.3   文件头注释示例

5.3.4   类定义注释示例


 
 
    

  
  
  1. /**    本类的功能：打印错误信息  
    2. 

  
  
  2.  *   
    3. 

  
  
  3.  *     本类是一个单件  
    4. 

  
  
  4.  *     在程序中需要进行错误信息打印的地方  
    5. 

  
  
  5.  */ 
    6. 

  
  
  6. class CPrintError  
    7. 

  
  
  7. {  
    8. 

  
  
  8.             ……  
    9. 

  
  
  9. } 
    10.

5.3.5   类成员变量定义示例

（ 1 ）在成员变量上面加注释的格式 

   
   
    

    
    
  1. /** 成员变量描述 */ 
    2. 

    
    
  2. int  m_Var; 
    3.
（ 2 ）在成员变量后面加注释的格式 

  
  
    

   
   
  1. int  m_color;     /**< 颜色变量 */     
    2.

5.3.6   成员函数的注释示例


 
 
    

  
  
  1. /** 下面是一个含有两个参数的函数的注释说明（简述）  
    2. 

  
  
  2.  *  
    3. 

  
  
  3.  *     这里写该函数的详述信息  
    4. 

  
  
  4.  *     @param a 被测试的变量（param描述参数）  
    5. 

  
  
  5.  *     @param s 指向描述测试信息的字符串  
    6. 

  
  
  6.  *     @return    测试结果 （return描述返回值）  
    7. 

  
  
  7.  *     @see    Test()    （本函数参考其它的相关的函数，这里作一个链接）  
    8. 

  
  
  8.  *     @note    (note描述需要注意的问题)  
    9. 

  
  
  9.  */ 
    10. 

  
  
  10. int testMe(int a,const char *s); 
    11.

5.3.7     枚举变量的注释示例


 
 
    

  
  
  1. /**    颜色的枚举定义  
    2. 

  
  
  2.   *   
    3. 

  
  
  3.   *    该枚举定义了系统中需要用到的颜色\n  
    4. 

  
  
  4.   *    可以使用该枚举作为系统中颜色的标识  
    5. 

  
  
  5.   */ 
    6. 

  
  
  6. enum TEnum   
    7. 

  
  
  7. {   
    8. 

  
  
  8.      RED,           /**< 枚举，标识红色    */      
    9. 

  
  
  9.      BLUE,          /**< 枚举，标志蓝色    */      
    10. 

  
  
  10.      YELLOW         /**< 枚举，标志黄色. */      
    11. 

  
  
  11. }enumVar;    
    12.

5.4      C++风格的注释

5.4.1    概述

C++ 的注释风格主要使用下面这种样式： 即在注释块开始使用三个反斜杠 ‘ / ’
其他地方其实与 JavaDoc 的风格类似，只是 C++ 风格不用  “ * ”  罢了。

5.4.2       简述与详述

C++ 风格的简述与详述方式与 javaDoc 类似。
一般注释的描述由简述开始，经过特殊分隔方式后，后面紧跟详述的内容， C++ 风格可以使用的分隔方法有以下两种：
（1） 使用  \brief  参数标识，空行作为简述和详述的间隔标识
  

 
 
    

  
  
  1. ///    \brief  Brief description.  
    2. 

  
  
  2. ///    description continued.  
    3. 

  
  
  3. ///  
    4. 

  
  
  4. ///    Detailed description starts here.  
    5. 

  
  
  5. /// 
    6.
（ 2 ）  使用以空行（或者小数点加空格）作为简述与详述的分割
  

   
   
    

    
    
  1. ///   Brief description  
    2. 

    
    
  2. ///   description continued.  
    3. 

    
    
  3. ///     
    4. 

    
    
  4. ///   Detailed description starts here. 
    5.
以小数点加空格作为分隔如下： 

   
   
    

    
    
  1. ///         Brief description  
    2. 

    
    
  2. ///         description continued . （注意:这里有一个小数点,加上一个空格）  
    3. 

    
    
  3. ///         Detailed description starts here.  
    4. 

    
    
  4. /// 
    5.

5.4.3    注释风格约定

1. 一个代码块（类、函数、结构等）的概述采用单行的”///”加一个空格开头的注释，并写在该代码块声明的前面；
2. 一个代码块的详述采用至少两行的”///”加一个空格开头的注释，若不足两行第二行的开头也要写出来，并且放在代码块定义的前面；如果某代码没有声明只有定义或者相反，则在定义或者声明前面写上单行的概述+一个空行+多行的详述；
3. 枚举值列表的各项、结构域的各项等采用在本行最后添加”///<”加一个空格开头的注释；
4. 对变量的定义采用在变量上面加单行”///”加一个空格开头的注释（相当于是给改变量一个概述）；
5. 函数的参数用”/// @param”+一个空格开头的行描述在函数的详述里面；
6. 函数的返回值用”/// @return”+一个空格开头的行描述在函数的详述里面；
7. 函数之间的参考用”/// @see”+一个空格开头的行描述在函数的详述里面；
8. 文件头的版权以及文件描述的注释参见例代码。

5.4.4       文件头注释示例

5.4.5       类定义注释示例


 
 
    

  
  
  1. ///    本类的功能：打印错误信息  
    2. 

  
  
  2. ///  
    3. 

  
  
  3. ///    本类是一个单件  
    4. 

  
  
  4. ///    在程序中需要进行错误信息打印的地方  
    5. 

  
  
  5. class CPrintError  
    6. 

  
  
  6. {  
    7. 

  
  
  7.           ……  
    8. 

  
  
  8. }  
    9.

5.4.6       类成员变量定义示例

（ 1 ）在成员变量上面加注释的格式 

   
   
    

    
    
  1. /// 成员变量描述  
    2. 

    
    
  2. int  m_Var; 
    3.
（ 2 ）在成员变量后面加注释的格式 

  
  
    

   
   
  1. int  m_color;     /// 颜色变量    
    2.

5.4.7       成员函数的注释示例 


 
 
    

  
  
  1. /// 下面是一个含有两个参数的函数的注释说明（简述）   
    2. 

  
  
  2. ///    
    3. 

  
  
  3. ///     这里写该函数的详述信息    
    4. 

  
  
  4. ///     @param a 被测试的变量（param描述参数）    
    5. 

  
  
  5. ///     @param s 指向描述测试信息的字符串    
    6. 

  
  
  6. ///     @return    测试结果 （return描述返回值）   
    7. 

  
  
  7. ///     @see    Test()    （本函数参考其它的相关的函数，这里作一个链接）  
    8. 

  
  
  8. ///     @note    (note描述需要注意的问题)    
    9. 

  
  
  9. int testMe(int a,const char *s);  
    10.

5.4.8       枚举变量的注释示例

  

 
 
    

  
  
  1. ///    颜色的枚举定义  
    2. 

  
  
  2. ///   
    3. 

  
  
  3. ///    该枚举定义了系统中需要用到的颜色\n  
    4. 

  
  
  4. ///    可以使用该枚举作为系统中颜色的标识  
    5. 

  
  
  5. enum TEnum   
    6. 

  
  
  6. {   
    7. 

  
  
  7.     RED,            ///< 枚举，标识红色       
    8. 

  
  
  8.     BLUE,           ///< 枚举，标志蓝色       
    9. 

  
  
  9.     YELLOW          ///< 枚举，标志黄色.       
    10. 

  
  
  10. }enumVar;     
    11.

5.5     需要注意的问题

（1）Doxygen会忽略你在注释中加入的多余的换行，如果你希望保留两行注释之间的空行，那么，在该行加入 \n
 

6      Doxygen使用的常见问题小结

6.1     中文问题：中文注释在文档中是乱码

解决：在expert中的INPUT选项页的INPUT_ENCODEING中填入“GB2312”，这样基于GB的文本编辑器生成的代码就可以正常使用了。

6.2    图形问题：无法绘制类图协作图等图形。

解决：首先确保安装了graphviz for win，注意不是wingraphviz，后者是一个graphviz的com封装，但是doxygen并不是基于它开发的，所以装了也没用。然后在expert的DOT_PATH中填入graphviz的安装路径。接着在wizard的diagram中选择需要生成的图形类别就可以了。
如果出现无法包含.map文件的错误，可以将工作目录设置成html，并将html中所有文件都清除再试。这个问题的原因还不太确定。

6.3    输出chm的问题：如何输出.chm文件

配置时注意expert中的HTML页：选中“GENERATE_HTMLHELP”，然后在CHM_FILE中填上想要的chm文件名。
HHC_LOCATION中输入hhc.exe文件的路径。hhc.exe可以通过安装HTML Help Workshop获得。
或者使用HTML Help Workshop来编译Doxygen生成的html文件夹中的.hhp文件，编译完成后即可在该html文件夹中找到对应的chm文件

6.4     Doxygen无法为DLL中定义的类 导出文档

例如：
class __declspec(dllexport) CClassName:public CObject
{
}
目前发现Doxygen无法识别出DLL中定义的类。




本文转自 Jhuster 51CTO博客，原文链接：http://blog.51cto.com/ticktick/188674，如需转载请自行联系原作者
文章标签：
C++
测试技术
技术小阿哥
目录
相关文章
泡沫o0
|
8月前
|
自然语言处理 算法 前端开发
C++与Doxygen：精通代码文档化之道
C++与Doxygen：精通代码文档化之道
泡沫o0
616 0
程序三两行
|
8月前
|
Java 编译器 C语言
python安装、输入输出、注释、中文编码、编码规范等基础语法
python安装、输入输出、注释、中文编码、编码规范等基础语法
程序三两行
110 0
张志凌
|
2月前
|
编译器
R 语言教程 之 R 注释
R语言中的注释仅支持单行注释，使用#符号。多行注释可通过每行添加#或使用if(FALSE){}结构实现。注释帮助理解代码，但不参与执行。示例包括简单的打印语句和两数相加。
张志凌
51 4
simplify0
|
8月前
doxygen根据代码生成文档
doxygen根据代码生成文档
simplify0
44 0
2分钟速写快排
|
JavaScript 前端开发 IDE
写好你的注释之 JSDoc
好的代码，注释肯定不能少，就目前而言基于 vue 的项目大部分都是使用的 vue2，vue2 相对于 ts 的支持没有那么完善，大部分包括我目前工作所在的团队，使用的 vue 版本都是采用 vue2
2分钟速写快排
860 1
技术小阿哥
|
C++ 索引 JavaScript
Doxygen详细介绍（二）（Doxygen配置文件）
技术小阿哥
3399 0
OBKoro1
|
程序员 开发工具 git
骚注释一键添加佛祖保佑永无BUG、神兽护体等注释图形的VSCode插件
很早之前就见过各种佛祖保佑永无BUG、神兽护体等形式的注释，感觉很有趣，蛮骚的😉。 然后最近有人在我开源的VSCode插件：**koroFileHeader**里面给我提issue，希望能够支持这种类型的注释。 现在开发完成了，大家可以根据下面的使用方式试用一下。 koroFileHeader插件简介 这个插件目前维护两年多了，有1300+Star，支持所有主流语言，支持自定义语言(不支持的语言可以自行设置)。 作用: 在文件开头添加注释，记录文件信息/文件的传参/出参等，让人对文件的功能一目了然。 如果觉得还不错的话，就给我点个Star⭐️吧~ 插件示例:
OBKoro1
543 0
骚注释一键添加佛祖保佑永无BUG、神兽护体等注释图形的VSCode插件
OBKoro1
|
PHP 开发工具 git
VsCode 添加文件头部注释和函数注释[koroFileHeader]
koroFileHeader 在vscode中用于生成文件头部注释和函数注释的插件，经过多版迭代后，插件：支持所有主流语言,灵活方便，文档齐全，食用简单！觉得插件不错的话，就给个Star⭐️吧~ 文件头部添加注释: 在文件开头添加注释，记录文件信息/文件的传参/出参等 支持用户高度自定义注释选项, 适配各种需求和注释。 保存文件的时候，自动更新最后的编辑时间和编辑人 快捷键：window：ctrl+alt+i,mac：ctrl+cmd+i
OBKoro1
3468 0
VsCode 添加文件头部注释和函数注释[koroFileHeader]
技术小阿哥
|
Web App开发 程序员 C#
Doxygen详细介绍（一）（Doxygen概述及本系列文章目录）
技术小阿哥
1771 0
技术小胖子
|
Oracle 关系型数据库 PHP
php扩展模块作用及中文注释
技术小胖子
1107 0

热门文章

最新文章

  • 1
    持续定义SaaS模式云数据仓库+数据银行
  • 2
    patch 命令用法详解（转）
  • 3
    小程序审核常见驳回类型
  • 4
    评测：AI客服接入钉钉与微信的对比分析
  • 5
    一套优秀Java云HIS医院信息管理系统SaaS源码
  • 6
    BGP路径选择次序
  • 7
    65.shell特殊符号与和cut,sort,wc,uniq,tee,tr,split命令
  • 8
    samba客户端的总结与归纳
  • 9
    [PAL规范]SAP HANA PAL 数据处理装箱算法Binning编程规范BINNING
  • 10
    linux内核分析笔记----中断和中断处理程序【转】
  • 1
    TransPixar AI
    125
  • 2
    《docker基础篇：2.Docker安装》包括前提说明、Docker的基本组成、Docker平台架构图解(架构版)、安装步骤、阿里云镜像加速、永远的HelloWorld、底层原理
    158
  • 3
    通义万相2.1：VBench榜单荣登第一！阿里通义万相最新视频生成模型，支持生成1080P长视频
    103
  • 4
    GLM-Zero：智谱AI推出与 OpenAI-o1-Preview 旗鼓相当的深度推理模型，开放在线免费使用和API调用
    78
  • 5
    DeepSeek Artifacts：在线实时预览的前端 AI 编程工具，基于DeepSeek V3快速生成React App
    96
  • 6
    智能运维新时代：AI在云资源管理中的应用与实践
    55
  • 7
    假如AI欺骗了你 | AI大咖说
    117
  • 8
    写在最前的话
    47
  • 9
    深度强化学习实战：训练DQN模型玩超级马里奥兄弟
    114
  • 10
    体验《多模态数据信息提取》
    46

    • 相关电子书

    更多
  • 低代码开发师（初级）实战教程
  • 冬季实战营第三期：MySQL数据库进阶实战
  • 阿里巴巴DevOps 最佳实践手册
    • 下一篇
    DataWorks智能交互式数据开发与分析之旅