实用工具推荐----Doxygen使用方法

目录

目录

1 软件介绍

2 Doxygen软件下载方法

3 Doxygen软件配置方法

4 标准注释描述

4.1 块注释 和 特殊描述字符

4.1.1 函数描述示例

4.1.2结构体数组变量示例

特别注意：

4.2单行注释

4.2.1 单个变量注释示例

特别注意：

4.2.2对于枚举变量描述示例

4.3 markdown语法使用及效果

4.4 类图 & 流程图调用关系生成方法

1 软件介绍

Doxygen是通过注释过的源代码文件来生成文档的工具，常用的语言例如C、Objective-C、C#、PHP、Java、Python、IDL等。它可以从一组有文档的源文件生成在线文档浏览器（HTML格式）和/或离线参考手册（LaTeX格式）。它还支持生成 RTF（MS-Word）、PostScript、超链接 PDF、压缩 HTML、DocBook 和 Unix 手册页的输出。文档直接从源代码中提取，这使得保持文档与源代码的一致性变得更加容易。可以配置 Doxygen 从未文档化的源文件中提取代码结构。这对于在大型源代码分发中快速找到方向非常有用。Doxygen 还可以通过包含依赖图、继承图和协作图来可视化各个元素之间的关系，所有这些都会自动生成。

Doxygen是开源软件，遵循GUN开源协议，因此生成的文档是从其生产中使用的输入派生的衍生作品;他们不受此许可证的影响。

开源Github网址：GitHub - doxygen/doxygen: Official doxygen git repository

Doxygen官网：Doxygen homepage

2 Doxygen软件下载方法

软件下载网站参照官网：Doxygen download

可以在不同系统上下载不同版本安装包，默认安装即可。

3 Doxygen软件配置方法

安装后在安装目录下可以看到 doxygen\bin\doxywizard.exe 程序

点击打开后可以看到运对应的GUI界面

首先填写 Project信息

然后填写模式信息

选择输出文档模式

关于生成类图的选项

选择 Expert 可以配置更多内容，例如在input中可以追加中文源码分析，鼠标悬停在各个选项上时有更详细的解释

上述内容配置好后，可以点击file或者ctrl+s保存配置。开发上各个域或模块情况不一样，每部分作业可以按照自己的需求定制化配置进行保存，开发者导入配置文件后标准化注释后直接导出文件即可。

进入Run界面，点击Run doxygen开始生成相关文档，点击 Show HTML output，可以查看生成的文档内容

4 标准注释描述

4.1 块注释 和 特殊描述字符

 标准注释方法可以参照 官方文档中Special Commands章节

下载连接：https://www.doxygen.nl/files/doxygen_manual-1.12.0.pdf.zip

常用的commands例如

可以描述的内容很多例如：函数、变量、类型定义、枚举、枚举值、宏定义都可以进行相关描述

4.1.1 函数描述示例

这些Special Commands 使用位置要和需要注释说明的函数放到一起，同时整体注释使用如下方式进行

/*!
* @[Special Commands]
*/

 例如：

或者

/*!
* \[Special Commands]
*/

例如：

然后使用Doxygen生成文档此部分效果如下：

如果有需要也可以更改Doxygen配置生成其他语言效果

4.1.2结构体数组变量示例

代码：

效果展示：

特别注意：

这里值得注意的是上述描述中因为有 @todo 相关描述所以最终会在生成产物中todo list中体现相关信息如下：

4.2单行注释

（PS：更详细的内容参照

https://www.doxygen.nl/files/doxygen_manual-1.12.0.pdf.zip 中 Documenting the code 章节）

可以使用 /// 或 //！   

同时也可以在注释后再使用 @[Special Commands]的方式进行额外标注

4.2.1 单个变量注释示例

对于单个变量，往往会采用单行注释方法进行描述

效果如下：

特别注意：

上述注释方法需要将注释放到变量前使用，如果想要注释放到变量后使用

可以使用如下三种方法

效果展示：

4.2.2对于枚举变量描述示例

代码：

文档生成效果：

4.3 markdown语法使用及效果

TODO

4.4 类图 & 流程图调用关系生成方法

TODO