【CMake】C/C++工具：Doxygen最简使用说明

【CMake】C/C++工具：Doxygen最简使用说明

简介

开源跨平台的注释文档生成工具。

安装

1. 下载 doxygen
2. 解压tar zxvf doxygen压缩包
3. 切换到解压后的doxygen主目录cd doxygen解压目录
4. 创建build目录mkdir build
5. 切换到build目录cd build
6. 生成Linux Makefilecmake -G “Unix Makefiles” …/
7. 编译make
8. 安装make install

使用

1. 进入项目目录cd 项目目录
2. 生成配置文件doxygen –g (默认配置文件名为Doxyfile)
3. 生成文档文件doxygen

配置文件

# 项目名称，将作为于所生成的程序文档首页标题
PROJECT_NAME        = “Test”
# 文档版本号，可对应于项目版本号，譬如 svn、cvs 所生成的项目版本号
PROJECT_NUMBER      = "1.0.0
# 程序文档输出目录
OUTPUT_DIRECTORY    =  /home/user1/docs
 
# 程序文档输入目录 
INPUT                = /home/user1/project/kernel
 
# 程序文档语言环境
OUTPUT_LANGUAGE      = Chinese
DOXYFILE_ENCODING  = UTF-8
# 只对头文件中的文档化信息生成程序文档 
FILE_PATTERNS        = 
 
# 递归遍历当前目录的子目录，寻找被文档化的程序源文件 
RECURSIVE            = YES 
# 如果是制作 C 程序文档，该选项必须设为 YES，否则默认生成 C++ 文档格式
OPTIMIZE_OUTPUT_FOR_C  = YES
 
#提取信息，包含类的私有数据成员和静态成员
EXTRACT_ALL            = yes
EXTRACT_PRIVATE        = yes
EXTRACT_STATIC        = yes
# 对于使用 typedef 定义的结构体、枚举、联合等数据类型，只按照 typedef 定义的类型名进行文档化
TYPEDEF_HIDES_STRUCT  = YES
# 在 C++ 程序文档中，该值可以设置为 NO，而在 C 程序文档中，由于 C 语言没有所谓的域/名字空间这样的概念，所以此处设置为 YES
HIDE_SCOPE_NAMES      = YES
# 让 doxygen 静悄悄地为你生成文档，只有出现警告或错误时，才在终端输出提示信息
QUIET  = YES
# 递归遍历示例程序目录的子目录，寻找被文档化的程序源文件
EXAMPLE_RECURSIVE      = YES
# 允许程序文档中显示本文档化的函数相互调用关系
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION    = YES
REFERENCES_LINK_SOURCE = YES
# 不生成 latex 格式的程序文档
GENERATE_LATEX        = NO
# 在程序文档中允许以图例形式显示函数调用关系，前提是你已经安装了 graphviz 软件包
HAVE_DOT              = YES
CALL_GRAPH            = YES
CALLER_GRAPH          = YES
#在最后生成的文档中，把所有的源代码包含在其中
SOURCE BROWSER        = YES
$这会在HTML文档中，添加一个侧边栏，并以树状结构显示包、类、接口等的关系
GENERATE TREEVIEW      ＝ ALL

No.	文件格式	选项	值	默认值	作用	相关选项
1	LaTeX	GENERATE_LATEX	YES/NO	YES	产生LaTeX的文件	LATEX_OUTPUT输出目录，默认latex
2	rtf	GENERATE_RTF	YES/NO	YES	产生rtf的文件	RTF_OUTPUT输出目录，默认rtf
3	man	GENERATE_MAN	YES/NO	NO	Unix Man Page 格式	MAN_OUTPUT输出目录，默认man
4	rtf	GENERATE_XML	YES/NO	NO	产生xml的文件	XML_OUTPUT输出目录，默认xml

语法简介

• 简单注释
• 单行注释：///或者//!
• 多行注释：/**或者/*!
• 文件注释

/**
 * @file 文件名
 * @brief 简介
 * @details 细节
 * @mainpage 工程概览
 * @author 作者
 * @version 版本号
 * @date 年-月-日
 */

---

• 全局常量/变量/宏定义/结构体定义/类定义的注释
• 代码前注释

/// 注释
全局常量/变量/宏定义/结构体定义/类定义

例如：

/// 缓存大小
#define BUFSIZ 1024*4

---

• 代码后注释

全局常量/变量/宏定义/结构体定义/类定义 ///< 注释

例如：

#define BUFSIZ 1024*4 ///< 缓存大小

---

• 函数注释

/**
 * @brief 函数简介
 *
 * @param 形参 参数说明
 * @param 形参 参数说明
 * @return 返回值说明
*/

例如：

/**
 * @brief 主函数
 * @details 程序唯一入口
 *
 * @param argc 命令参数个数
 * @param argv 命令参数指针数组
 * @return @c 0 程序执行成功
 *               @c 1 程序执行失败
*/
int main(int argc, char* argv[]){
}

命令	生成字段名
@param	参数
@return	返回值
@p	参数(后面紧接单词是参数)
@c	代码(后面紧接单词是代码)

其它常用命令

命令	生成字段名	说明
@attention	注意
@bug	缺陷	链接到所有缺陷汇总的缺陷列表
@warning	警告
@see	参考
@code	代码块开始	与@endcode成对使用
@endcode	代码块结束	与@code成对使用
@todo	TODO	链接到所有TODO 汇总的TODO 列表

其他

使用Visual Assist X进行快捷doxygen模板注释