126 lines
5.3 KiB
Markdown
126 lines
5.3 KiB
Markdown
|
# 使用Doxygen实现C++代码注释自动生成开发手册
|
|||
|
|
|
|||
|
|
## 安装Graphviz软件
|
|||
|
|
1. 安装doxygen-1.9.3-setup.exe，安装成功后运行；
|
|||
|
|
|
|||
|
|
2.选择所有对象
|
|||
|
|
3. 选择代码所用到的语言
|
|||
|
|
|
|||
|
|
4. 选择生成.chm格式的文档
|
|||
|
|
|
|||
|
|
5. 选择使用GraphViz来生成类图
|
|||
|
|
|
|||
|
|
6. 选择输出语言
|
|||
|
|
|
|||
|
|
|
|||
|
|
> - CHM_FILE： 最终生成的.chm的文件名，默认为index.chm
|
|||
|
|
> - HHC_LOCATION： chm 编译器（hhc.exe）的全路径。请指到 HTML Help Workshop 的安装目录的 hhc.exe 程序
|
|||
|
|
> - CHM_INDEX_ENCODING： chm索引文件编码
|
|||
|
|
> 
|
|||
|
|
|
|||
|
|
> - EXTRACT_ALL 表示：输出所有的函数，但是private和static函数不属于其管制。
|
|||
|
|
> - EXTRACT_PRIVATE 表示：输出private函数。
|
|||
|
|
> - EXTRACT_STATIC 表示：输出static函数。
|
|||
|
|
> - SHOW_INCLUDE_FILES 表示：是否显示包含文件，如果开启，帮助中会专门生成一个页面，里面包含所有包含文件的列表。
|
|||
|
|
> - INLINE_INFO ：如果开启，那么在帮助文档中，inline函数前面会有一个inline修饰词来标明。
|
|||
|
|
> - SORT_MEMBER_DOCS ：如果开启，那么在帮助文档列表显示的时候，函数名称会排序，否则按照解释的顺序显示。
|
|||
|
|
> 
|
|||
|
|
|
|||
|
|
INPUT_ENCODING 中文注释乱码解决方法
|
|||
|
|
FILE_PATTERNS 生成帮助文档所需要文件后缀 可添加 可删除
|
|||
|
|
RECURSIVE 选择递归的方式
|
|||
|
|
|
|||
|
|
|
|||
|
|
显示类图
|
|||
|
|
|
|||
|
|
|
|||
|
|
最后运行生成
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
## Doxygen 注释规范
|
|||
|
|
### 1.1 头文件模板:
|
|||
|
|
/*! @brief 摘要
|
|||
|
|
* @file 文件名
|
|||
|
|
* @author 作者
|
|||
|
|
* @version 版本号
|
|||
|
|
* @date 你啥时候搞的
|
|||
|
|
* @note 注解
|
|||
|
|
* @since 从哪个版本后开始有这个函数的
|
|||
|
|
*/
|
|||
|
|
|
|||
|
|
### 1.2 函数的注释:
|
|||
|
|
/*! 这里写这个函数是干什么用的
|
|||
|
|
@param i1[in] 输入参数1
|
|||
|
|
@param i2[in] 输入参数2
|
|||
|
|
@param o3[out] 输出参数1
|
|||
|
|
@return 返回值解释一下
|
|||
|
|
@warning 警告: 例如: 参数不能为空
|
|||
|
|
@note 注解
|
|||
|
|
@see 相当于是请参考xxoo函数之类的
|
|||
|
|
关于bool量返回值
|
|||
|
|
@retval 1 成功
|
|||
|
|
@retval 0 失败
|
|||
|
|
*/
|
|||
|
|
|
|||
|
|
###1.3 行注释模板
|
|||
|
|
/**< 在这里写你要加的东西 */
|
|||
|
|
///< 在这里写你要加的东西
|
|||
|
|
常用的关键字
|
|||
|
|
@mainpage 项目工程概述
|
|||
|
|
@author 作者的信息
|
|||
|
|
@brief 用于class 或function的简易说明 eg：@brief 本函数负责打印错误信息串
|
|||
|
|
@bug 被标记的代码会在Bug列表中出现
|
|||
|
|
@date 日期
|
|||
|
|
@file 文件名，可以默认为空，DoxyGen会自己加
|
|||
|
|
@param 主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明
|
|||
|
|
@return 描述该函数的返回值情况eg: @return 本函数返回执行结果，若成功则返回TRUE，否则返回FLASE
|
|||
|
|
@retval 描述返回值类型 eg: @retval NULL 空字符串。@retval !NULL 非空字符串。
|
|||
|
|
@note 注解
|
|||
|
|
@attention 注意
|
|||
|
|
@name 分组名
|
|||
|
|
@warning 警告信息
|
|||
|
|
@todo 对将要做的事情进行注释
|
|||
|
|
@see see also字段
|
|||
|
|
@relates 通常用做把非成员函数的注释文档包含在类的说明文档中。
|
|||
|
|
@since 从哪个版本后开始有这个函数的
|
|||
|
|
@code 在注释中开始说明一段代码，直到@endcode命令。
|
|||
|
|
@endcode 在注释中代码段的结束。
|
|||
|
|
@remarks 备注
|
|||
|
|
@pre 用来说明代码项的前提条件。
|
|||
|
|
@post 用来说明代码项之后的使用条件。
|
|||
|
|
@deprecated 这个函数可能会在将来的版本中取消。
|
|||
|
|
@defgroup 模块名
|
|||
|
|
@{ 模块开始
|
|||
|
|
@} 模块结束
|
|||
|
|
@class 声明一个类 可对类进行详细描述
|
|||
|
|
@version 版本号
|
|||
|
|
@fn 声明一个函数
|
|||
|
|
@par 开始一个段落，段落名称描述由你自己指定，比如可以写一段示例代码
|
|||
|
|
- 一级项目符号
|
|||
|
|
- 二级项目符号
|
|||
|
|
\ref在注释中连接到函数 变量 类
|
|||
|
|
@exception 可能产生的异常描述 eg: @exception 本函数执行可能会产生超出范围的异常
|
|||
|
|
代码和帮助文档中显示的示例
|
|||
|
|
在看到函数详细介绍之前的简易介绍
|
|||
|
|
|
|||
|
|
|
|||
|
|
枚举定义
|
|||
|
|
|
|||
|
|
|
|||
|
|
需要将内容框选出来时使用
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
行注释
|
|||
|
|
|
|||
|
|
|
|||
|
|
函数注释和一些链接 使用\ref时需要留出空格
|
|||
|
|
|
|||
|
|
|
|||
|
|
对当前类的一个详细概述
|
|||
|
|
|
|||
|
|
|
|||
|
|
对当前工程介绍
|
|||
|
|
|
|||
|
|
|