网站建设与管理专业就业前景,天津专业制作网站,微信小程序开店需要多少钱,wordpress检索蜘蛛插件文章目录简介Doxygen的安装Doxygen的配置生成配置文件常用配置Doxygen注释头文件注释:函数的注释:Doxygen文档生成reference简介
Doxygen 是一个流行的用于生产代码文档的工具#xff0c;关于它的介绍可以参考官网#xff1a;https://www.doxygen.nl/index.html。 我使用Dox…
文章目录简介Doxygen的安装Doxygen的配置生成配置文件常用配置Doxygen注释头文件注释:函数的注释:Doxygen文档生成reference简介
Doxygen 是一个流行的用于生产代码文档的工具关于它的介绍可以参考官网https://www.doxygen.nl/index.html。 我使用Doxygen的目的主要有三个
生成在线文档方便阅读查看代码数据结构之间的关系在其他项目中快速索引本项目的接口文档
Doxygen支持许多语言我主要使用C/C生成的文档主要是HTML,生成后在浏览器中打开浏览。
Doxygen的安装
sudo apt install doxygen
sudo apt install graphviz其中graphviz是一个强大的程序绘图工具它的使用可以参考Graphviz入门
Doxygen的配置
生成配置文件
进入项目目录:
doxygen -g该命令会在当前路径生成一个名为Doxyfile配置文件.
Doxyfile 文件内容非常多大概 1000 多行不过其中大部分都是注释每个配置选项都有一段详细的注释。如果对 Doxygen 各配置选项的意义有一定了解可以在生成配置文件的命令中添加 “-s” 选项生成不含注释的配置文件操作如下
doxygen -s -g常用配置
执行完上面的生成命令, 已经有个模板Doxyfile可以根据需要更改相应设置:
# 项目名称将作为于所生成的程序文档首页标题
PROJECT_NAME TEST# 文档版本号可对应于项目版本号譬如 svn、cvs 所生成的项目版本号
PROJECT_NUMBER 1.0.0
# 程序文档输出目录
OUTPUT_DIRECTORY doc-reference
# 程序文档语言环境
OUTPUT_LANGUAGE Chinese
# 如果是制作 C 程序文档该选项必须设为 YES否则默认生成 C 文档格式
OPTIMIZE_OUTPUT_FOR_C YES
# 对于使用 typedef 定义的结构体、枚举、联合等数据类型只按照 typedef 定义的类型名进行文档化
TYPEDEF_HIDES_STRUCT YES
# 在 C 程序文档中该值可以设置为 NO而在 C 程序文档中由于 C 语言没有所谓的域/名字空间这样的概念所以此处设置为 YES
HIDE_SCOPE_NAMES YES
# 让 doxygen 静悄悄地为你生成文档只有出现警告或错误时才在终端输出提示信息
QUIET YES
# 只对头文件中的文档化信息生成程序文档
FILE_PATTERNS *.h
# 递归遍历当前目录的子目录寻找被文档化的程序源文件
RECURSIVE YES
# 示例程序目录
EXAMPLE_PATH example/
# 示例程序的头文档 (.h 文件) 与实现文档 (.c 文件) 都作为程序文档化对象
EXAMPLE_PATTERNS *.c *.h
# 递归遍历示例程序目录的子目录寻找被文档化的程序源文件
EXAMPLE_RECURSIVE YES
# 允许程序文档中显示本文档化的函数相互调用关系
REFERENCED_BY_RELATION YES
REFERENCES_RELATION YES
REFERENCES_LINK_SOURCE YES
# 生成 latex 格式的程序文档
GENERATE_LATEX YES
# 在程序文档中允许以图例形式显示函数调用关系前提是你已经安装了 graphviz 软件包
HAVE_DOT YES
CALL_GRAPH YES
CALLER_GRAPH YES
#让doxygen从配置文件所在的文件夹开始递归地搜索所有的子目录及源文件
RECURSIVE YES
#在最后生成的文档中把所有的源代码包含在其中
SOURCE_BROWSER YES
$这会在HTML文档中添加一个侧边栏并以树状结构显示包、类、接口等的关系
GENERATE_TREEVIEW ALL模板
# 项目名称将作为于所生成的程序文档首页标题
PROJECT_NAME “Test
# 文档版本号可对应于项目版本号譬如 svn、cvs 所生成的项目版本号
PROJECT_NUMBER 1.0.0
# 程序文档输出目录
OUTPUT_DIRECTORY doc/
# 程序文档语言环境
OUTPUT_LANGUAGE Chinese
# 如果是制作 C 程序文档该选项必须设为 YES否则默认生成 C 文档格式
OPTIMIZE_OUTPUT_FOR_C YES
# 对于使用 typedef 定义的结构体、枚举、联合等数据类型只按照 typedef 定义的类型名进行文档化
TYPEDEF_HIDES_STRUCT YES
# 在 C 程序文档中该值可以设置为 NO而在 C 程序文档中由于 C 语言没有所谓的域/名字空间这样的概念所以此处设置为 YES
HIDE_SCOPE_NAMES YES
# 让 doxygen 静悄悄地为你生成文档只有出现警告或错误时才在终端输出提示信息
QUIET YES
# 只对头文件中的文档化信息生成程序文档
FILE_PATTERNS *.h
# 递归遍历当前目录的子目录寻找被文档化的程序源文件
RECURSIVE YES
# 示例程序目录
EXAMPLE_PATH example/
# 示例程序的头文档 (.h 文件) 与实现文档 (.c 文件) 都作为程序文档化对象
EXAMPLE_PATTERNS *.c \*.h
# 递归遍历示例程序目录的子目录寻找被文档化的程序源文件
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
#让doxygen从配置文件所在的文件夹开始递归地搜索所有的子目录及源文件
RECURSIVE YES
#在最后生成的文档中把所有的源代码包含在其中
SOURCE BROWSER YES
$这会在HTML文档中添加一个侧边栏并以树状结构显示包、类、接口等的关系
GENERATE TREEVIEW ALLDoxygen注释
Doxygen就是从源代码文件的注释中提取文档. 所以生成文档之前, 就是要按照Doxygen的风格来编写注释。
头文件注释:
/** brief 这里写你的摘要* file 你的文件名* author 作者* version 版本* date 日期* note 注解. 例如: 本文件有什么具体功能啊, 使用时要注意什么啊..* since 自从...*/函数的注释:
/** 这里写这个函数的概述param[in] 输入参数1param[in] 输入参数2param[out] 输出参数1return 返回值解释一下warning 警告: 例如: 参数不能为空之类的note 注解see 类似于请参考xxoo函数之类的
*/更多注释规则请查阅:
我主要使用vscode,可以安装doxygen插件结合配置可以自动触发注释我的配置如下 // Doxygen documentation generator set// 文件注释版权信息模板doxdocgen.file.copyrightTag: [copyright Copyright (c) {year} company/organization],// 文件注释自定义模块这里我添加一个修改日志doxdocgen.file.customTag: [par 修改日志:,table,trthDate thVersion thAuthor thDescription,trtd{date} td1.0 tdczw td内容,/table,],// 文件注释的组成及其排序doxdocgen.file.fileOrder: [file, // filebrief, // brief 简介author, // 作者version, // 版本date, // 日期empty, // 空行copyright,// 版权empty,custom // 自定义],// 下面时设置上面标签tag的具体信息doxdocgen.file.fileTemplate: file {name},doxdocgen.file.versionTag: version 1.0,doxdocgen.generic.authorEmail: nameaddress,doxdocgen.generic.authorName: name,doxdocgen.generic.authorTag: author {author} ({email}),// 日期格式与模板doxdocgen.generic.dateFormat: YYYY-MM-DD,doxdocgen.generic.dateTemplate: date {date},// 根据自动生成的注释模板目前主要体现在函数注释上doxdocgen.generic.order: [brief,details,tparam,param,return],doxdocgen.generic.briefTemplate: brief {text},doxdocgen.generic.paramTemplate: param{indent:8}{param},doxdocgen.generic.returnTemplate: return {type} ,doxdocgen.generic.splitCasingSmartText: true,Doxygen文档生成
在上面生成的Doxyfile所在的路径, 输入
doxygen doxygen_configdoxygen_config 是 Doxygen 配置文件名如果按照本文配置, 在doc-reference目录下, 会有html, latex文件夹. 使用浏览器打开html目录中的 index.html 文件即可看到代码注释文档。
reference
https://www.doxygen.nl/index.htmlhttps://pages.cs.wisc.edu/~jignesh/cs564/notes/Doxygen.pdfhttps://www.doxygen.nl/manual/index.html
