日常开发除了编写优良的代码,同样需要写好可读的注释。但对于开发人员而言,要写好注释,也是一件挺繁琐的事,尤其是那类注释基本都是固定的格式,如源文件开头部分的声明,还有函数声明等。
而 doxygen 工具正好可以帮助生成固定的注释模板,可以少敲很多内容,极大的提高开发人员写注释的效率,下面以 vscode 为例进行安装使用说明。
一、vscode 安装 doxygen 插件
直接在插件商店搜索 Doxygen Documentation Generator 进行安装,安装完成后,打开用户配置(F1->Open Settings),增加如下配置:
// File copyright documentation tag. Array of strings will be converted to one line per element. Can template {year}.
"doxdocgen.file.copyrightTag": [
"@copyright Copyright (c) {year}"
],
// Additional file documentation. Array of strings will be converted to one line per element. Can template {year}, {date}, {author}, and {email}.
"doxdocgen.file.customTag": [],
// The order to use for the file comment. Values can be used multiple times. Valid values are shown in default setting.
"doxdocgen.file.fileOrder": [
"file",
"author",
"brief",
"version",
"date",
"empty",
"copyright",
"empty",
"custom"
],
// The template for the file parameter in Doxygen.
"doxdocgen.file.fileTemplate": "@file {name}",
// Version number for the file.
"doxdocgen.file.versionTag": "@version 0.1",
// Set the e-mail address of the author. Replaces {email}.
"doxdocgen.generic.authorEmail": "[email protected]",
// Set the name of the author. Replaces {author}.
"doxdocgen.generic.authorName": "your name",
// Set the style of the author tag and your name. Can template {author} and {email}.
"doxdocgen.generic.authorTag": "@author {author} ({email})",
// The template of the brief Doxygen line that is generated. If empty it won't get generated at all.
"doxdocgen.generic.briefTemplate": "@brief {text}",
// The format to use for the date.
"doxdocgen.generic.dateFormat": "YYYY-MM-DD",
// The template for the date parameter in Doxygen.
"doxdocgen.generic.dateTemplate": "@date {date}",
// The order to use for the comment generation. Values can be used multiple times. Valid values are shown in default setting.
"doxdocgen.generic.order": [
"brief",
"empty",
"tparam",
"param",
"return",
"custom"
],
// Custom tags to be added to the generic order. One tag per line will be added. You have to specify the prefix yourself.
"doxdocgen.generic.customTags": [],
// The template of the param Doxygen line(s) that are generated. If empty it won't get generated at all.
"doxdocgen.generic.paramTemplate": "@param {param} ",
// The template of the return Doxygen line that is generated. If empty it won't get generated at all.
"doxdocgen.generic.returnTemplate": "@return {type} ",
// Decide if the values put into {name} should be split according to their casing.
"doxdocgen.generic.splitCasingSmartText": true,
设置好后,在源码文件头输入 “/**” ,然后按回车,就可以看到如下自动生成的文件头注释了
在函数上面同样输入“/**”,然后按回车,可以看到如下自动生成的函数注释
二、使用 doxygen 命令生成注释文档
使用 doxygen 的另一个好处是可以通过 doxygen 命令工具针对符合 doxygen 格式的注释生成文档直接进行查看。
在 MAC 下直接使用如下命令进行安装:
brew install doxygen
安装完成后,在对应的代码目录下,执行如下命令先生成配置文件 Doxyfile
doxygen -g
然后针对默认生成的配置文件对一些配置项进行修改,下面列举说明了可能常用的配置项
配置项 | 说明 |
---|---|
PROJECT_NAME | 项目名称 |
PROJECT_NUMBER | 文档版本号 |
EXTRACT_ALL | 默认NO,设置成YES,则解析所有代码,即使没有对应的注释 |
EXTRACT_PRIVATE | 默认NO,设置成YES,则解析私有项 |
EXTRACT_STATIC | 默认NO,设置成YES,则解析静态项 |
INPUT | 指定需要解析的目录,以空格隔开 |
FILE_PATTERNS | 针对INPUT中的目录再具体匹配的文件,如*.h |
RECURSIVE | 递归检索文件 |
EXCLUDE | 排除指定目录不被解析 |
EXCLUDE_PATTERNS | 针对EXCLUDE中的目录指定排除的文件,如/.git/ |
HAVE_DOT | 使用dot工具进行绘图,需要安装Graphviz |
CALL_GRAPH、CALLER_GRAPH | 绘制调用关系,需要先将HAVE_DOT置成YES |
OPTIMIZE_OUTPUT_FOR_C | 如果针对的是C代码,可以指定为YES |
HIDE_SCOPE_NAMES | C 语言不存在域名空间,可以设置为YES |
TYPEDEF_HIDES_STRUCT | 按照 typedef 定义的类型名进行文档化 |
GENERATE_LATEX | 不生成latex格式文档,置YES |
GENERATE_TREEVIEW | 生成侧边栏 |
GENERATE_HTMLHELP | 生成 .chm 格式文件 |
REFERENCED_BY_RELATION、REFERENCES_RELATION、REFERENCES_LINK_SOURCE | 显示的函数相互调用关系 |
修改完成之后,直接再执行命令 doxygen
即可,然后打开 html 目录下的 index.html 文件就可查看接口说明文档。