doxygen上手

Posted 2020-12-23 answerinthewind

doxygen {#mainpage}

doxygen是干什么的

相信大家在看MCU原厂的帮助文档的时候，都能看到doxygen的logo在右下角，没错，doxygen就是用来生成帮助文档的

doxygen可以根据代码中的注释信息，来生成代码的一个帮助文档

软件安装

doxygen安装

1. 上doxygen官网下载

2. 安装，安装就很简单，一路next就完事了

3. 安装完发现并没有生成桌面快捷方式，但是可以在windos的start或者安装目录找到，来一波添加桌面快捷方式

html Help (CHM) Help Compiler 安装

1. HHC是用来生成CHM文件的，所以也会用到
   去官网下载

下载doxygen中文手册

我从网上找到了这个doxygen的中文手册,给放在我的gitee上了，对于我这个英文不是很好的人来说，这个资料算是格外的珍贵了，也给大家分享一下

doxygen GUI frontend的使用

下面我都是使用这个GUI的程序来进行的

需要注意的地方

Expert->Input

注意，需要吧用到的资源的所有文件夹都包含进去，不然生成CHM可能会缺失

其他的就参见gitee上的工程文件吧

代码添加注释(VSCode korofileheader插件)

"fileheader.customMade":{
    "file":"",
    "Author": "chenjk",
    "Date": "Do not edit",
    "LastEditTime": "Do not edit",
    "FilePath": "Do not edit",
    "Description": "",
},
"fileheader.cursorMode": {
    "brief":"",
    "param":"",
    "return":"",
},
"fileheader.configObj": {
    "createHeader": true,   //默认打开
    "colon":" ",
    "annotationStr": {
        "head": "/**", // 自定义注释头部
        "middle": " * @", // 自定义注释中间部分(注意空格,这也是最终生成注释的一部分)
        "end": " */", // 自定义注释尾部
        "use": false // 是否使用自定义注释符号
    }
}

安装完之后，使用CTRL+ALT+I可以向代码中添加文件头部信息，使用CTRL+ALT+T可以添加函数注释格式信息，但因为我电脑的CTRL+ALT+T快捷键冲突了，我只能改建成CTRL+ALT+U，改键方法如下

注释

doxygen会识别如下如下格式的内容为用户需要doxygen进行抽取的

/**
 *
 */

其中第一行的第二个*即提示doxygen此处有需要抽取的注释，否则doxygen并不会进行检查

@或者符号是命令的提示符

比如命令brief为描述，在其前面添加@doxygen就会识别到这个命令，同理param也需要在前面加上@符号

常见的注释格式为:

建议在其中这个注释可以放在.c文件也可以放在.h文件，建议是如果存在.c文件，那么放在.c中，否则放在.h文件中。

另外如果两个都有，建议.h放简单的描述和输入输出的参数说明，若有更复杂的Note、Waring、details等，放在.c文件中

特殊命令

addtogroup

是将API分门别类的好工具，具体的效果就是会在生成的chm或HTML中增加一个模块页面增加这个组，这个组中会列举组中API的函数、枚举、定义等内容，所以如果需要代码API需要按模块来分类，并且可以配合brief来对模块进行说明，这是个利器

mainpage命令

我们可以使用md文件来制作首页，其方法就是在一级标题后面添加 {#mainpage},并且把这个文件添加到input中去

Note:

? 1. 但注意这个一定要是在md文件的最开头,并且前面没有东西

具体项目发布在我的gitee上了