Doxygen详细配置使用说明

写在前面：

Doxygen是自动生成帮助文档的软件，非常方便。

但，前提你的代码注释必须规范（这里的规范不是说符合你们公司内部规范，是符合标准规范）

另外，源码必须全部UTF8或GBK，不能混用（否则中文会出现乱码，当然注释全英文随意）

 

千万要注意以上两点，否则可能会出现乱码/ 失败之类的

 

什么是Doxygen？

Doxygen 是一个程序的文件产生工具，可将程序中的特定注释转换成为说明文件。说白了就是通过代码里注释直接生成说明文档，这样可以大大提高我们程序员生成说明文档的效率，当然前提我们程序代码注释要符合规范且比较合理，否则巧妇难为无米之炊。生成说明文档格式支持很多种，常见的如Html、chm、LATEX、RTF参考手册等等。

在这里 推荐生成chm格式，chm格式是微软推荐的帮助文档，支持查询、分类浏览，使用起来很方便。

（以下均是以chm格式为准，其他格式的，可以尝试下）

 

准备工作：

       要生成chm格式的文档，首先得安装chm制作工具（如果已经安装HTML Help Workshop，请跳过这一步）。注意chm制作工具要额外安装，不是Doxygen自带的。

       具体下载路径：官网下载

https://docs.microsoft.com/zh-cn/previous-versions/windows/desktop/htmlhelp/microsoft-html-help-downloads

 

       安装Doxygen

       Doxygen是开源项目，大家可以通过github进行下载。

       直接从官网地址下载也可以：官网下载

http://www.doxygen.nl/download.html

 

两个都要选择适合系统版本进行安装，安装过程很简单，这里不再复述。值得注意的是，要记住HTML Help Workshop的安装路径，这个路径后面要用到的。

 

开始操作：

       操作之前先介绍下涉及到几个重要的文件或文件夹：

• 运行根目录：

这个目录是指当前Doxygen运行的路径，建议将2、3、4这几个都放在这个文件下。

 

• 源码存放的文件夹：

就是你要转之前的源码文件，比如所有cpp h文件都放在这个下面

 

• 生成文档存放的文件夹：

生成之后存放位置

 

• Doxygen配置文件存放位置：

每个工程都应该有自己的Doxygen配置文件，这个可以通过拷贝其他工程的配置文件进行改进的，这样方便一点。

 

Step1: 配置路径

运行Doxygen就可以看这个界面，这个界面看似很多，实际只要捋清楚几个关键目录就没问题。当然如果你是直接打开其他其他工程的配置文件，这里会简单很多，当然看了图示，就更明白哪些地方是需要更改的，哪些地方不需要改的。

 

Step2: Mode选择，一般来说这步骤基本不用改动。

 

Step3: OutPut设置，这里要配置下，跟默认的不一致。特别是红色框，需要注意。

Step4: Expert-Project设置

Step5: Expert-Input设置，这样要注意的是输入ENCODING，即源码的编码格式，如果是GBK的要写成GBK的，否则中文会是乱码。

 

Step6: Expert-Build设置，把右边的几个勾上(勾上之后,字体就会变成红色)

 

Step7: Expert-HTML设置，这步骤很重要，内容也比较多。详见图示，注意红色的部分，要保持一致。

 

Step8: Expert-LaTex设置，这步骤比较简单,去掉原先打勾就可以了。

Step9: Expert-Dot设置，这步骤也很简单。

注意:

Expert配置项内容很多，也是主要配置内容，除了我已经图示几个地方，还有很多其他地方，当然没有图示的地方就按默认配置就可以了。

 

配置好参数之后，进入最后一个步骤，Run，类似编译。

“*** Doxygen has finished” 结束。

如果一切成功，就会生成我们的chm文件。当然如果有错误的话，可根据提示去看看是否配置出错，因为配置项比较多，难免会有点遗漏的。

 

 

=======================================================================

Doxygen 注释 要求（不完全统计）

并非所有程序代码中的注释都会被Doxygen所处理，而是必须依照正确的格式撰写。原则上，Doxygen仅处理与程序结构相关的注释，如Function，Class等。对于Function内部的注释则不做处理。Doxygen可处理下面几种类型的注释。

 

JavaDoc类型：

/*    * ... 注释 ...    */

 

Qt类型的注释：

/*!    * ... 注释 ...    */

 

单行类型的注释：

/// ... 注释 下一行  ...   或     //! ... 注释 下一行 ...

 

备注：不同类型的注释可以混合使用。(虽然是可以混用的，但还是统一一种风格比较好)

 

由于Doxygen 对于注释是视为在解释后面的程序代码。也就是说，任何一个注释都是在说明其后的程序代码。如果要注释前面的程序代码则需用下面格式的注释符号。（不推荐！！）

参数后面的注释，包含h文件里的函数申明也是。如果是在后面注释的，必须这样写   /*!< ... 注释前面的代码 ... */ /**< ... 注释前面的代码... */ //!< ... 注释前面的代码... ///< ... 注释前面的代码...   这里必须强调一下：如果不加<，则会认为是 下一行 的注释

 

Doxygen产生说明文档时，Doxygen会首先解析程序源代码，并且依据程序的结构建立对应的文档，然后再将代码中的注释依据其在程序中的位置放在文档中正确的地方。除了一般文字说明外，Doxygen中还有一些其它特别的指令，如@param及@return等。Doxygen根据这些指令判断注释的是函数参数还是返回值。例如Doxygen中对文件的注释如下所示：

 

 

/** ******************************************************************************* * @copyright * 高新兴创联科技有限公司 * *------------------------------------------------------------------------------ * @file     SocketUDP.h * @brief    Windows版本，UDP传输封装 * @author   xxxx * @date     2019-04-08 * @version  V0.1 * @note     新建,增加注释 ******************************************************************************* */

 

@file会告诉Doxygen此处是源码文件的注释，

@brief表明此处是文件的简易说明

@author表示的是作者信息。

 

对函数说明的注释如下所示：

/** ******************************************************************************* * @brief        初始化数据回调(接收到数据之后回调) * @param        strIP         本地IP,若不需要指定(默认)，可以strIP=NULL * @param        nPort         本地端口 * * @return       打开结果 *               =<em> -1 </em>打开失败 *               =<em> -2 </em>绑定失败 *               =<em> 0 </em> 打开成功 ******************************************************************************* */ int CSocketUDP::OpenPort(const char *strIP,const int nPort) { return -1； }

 

上面这个例子要说的是，在Doxygen处理一个函数注释时，会先判断第一行为简易说明。这个简易说明将一直到空一行的出现，或是遇到第一个 "." 为止。之后的注释将会被视为详细说明。@param表示是函数参数说明。在上面两个例子中"@"和"\"在Doxygen 中是一样的，都是告诉Doxygen后面是一个指令。

 

Doxygen中常用指令的说明如下表所示：

 

@file源码文件的注释说明。

 

@author作者的信息

 

@brief用于class 或function的注释中，后面为class 或function的简易说明。

 

@param格式为@param arg_name 参数说明

 

主要用于函式说明中，后面接参数的名字，然后再接关于该参数的说明。

 

@return后面接函数传回值的说明。用于function的注释中。说明该函数的传回值。

 

@retval 传回值说明

主要用于函式说明中，说明特定传回值的意义。所以后面要先接一个传回值。然后在放该传回值的说明。