doxygen自动生成代码注释文档

Posted by 周思进 on March 28, 2021

日常开发除了编写优良的代码,同样需要写好可读的注释。但对于开发人员而言,要写好注释,也是一件挺繁琐的事,尤其是那类注释基本都是固定的格式,如源文件开头部分的声明,还有函数声明等。

而 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,

设置好后,在源码文件头输入 “/**” ,然后按回车,就可以看到如下自动生成的文件头注释了

image

在函数上面同样输入“/**”,然后按回车,可以看到如下自动生成的函数注释

image


二、使用 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 文件就可查看接口说明文档。