使用doxygen或者koroFileHeader

doxygen with vscode

vscode安装插件Doxygen Document.
打开setting.json文件，插入以下customTag模块，在自动生成的文件说明中，添加历史记录信息：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
"doxdocgen.file.copyrightTag": [
        "@copyright Copyright (c)  {year} ***company All rights reserved."
    ],
"doxdocgen.file.versionTag": "@version 0.0.1",

"doxdocgen.generic.authorName": "Shona",
"doxdocgen.generic.authorTag": "@author {author}",
"doxdocgen.file.customTag": [
        "@par History:",
        "<table>",
        "<tr><th>Date        <th>Version  <th>Author    <th>Description",
        "<tr><td>{date}  <td>0.1      <td>Shona     <td>  ",
        "</table>"
    ],
"doxdocgen.file.fileOrder": [
    "file",
    "brief",
    "author",
    "version",
    "date",
    "empty",
    "copyright",
    "empty",
    "custom"
],
"doxdocgen.generic.order": [
        "brief",
        "tparam",
        "param",
        "return"
    ],
"doxdocgen.generic.paramTemplate": "@param{indent:8}{param}{indent:25}My Param doc",
"doxdocgen.generic.returnTemplate": "@return {type} ",
"doxdocgen.generic.splitCasingSmartText": true,

解释如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
{
    // Doxygen documentation generator set
    // 文件注释：版权信息模板
    "doxdocgen.file.copyrightTag": [
        "@copyright Copyright (c) {year}  XX通信公司"
    ],
    // 文件注释：自定义模块，这里我添加一个修改日志
    "doxdocgen.file.customTag": [
        "@par 修改日志:",
        "<table>",
        "<tr><th>Date       <th>Version <th>Author  <th>Description",
        "<tr><td>{date} <td>1.0     <td>shona     <td>内容",
        "</table>",
    ],
    // 文件注释的组成及其排序
    "doxdocgen.file.fileOrder": [
        "file",		// @file
        "brief",	// @brief 简介
        "author",	// 作者
        "version",	// 版本
        "date",		// 日期
        "empty",	// 空行
        "copyright",// 版权
        "empty",
        "custom"	// 自定义
    ],
    // 下面时设置上面标签tag的具体信息
    "doxdocgen.file.fileTemplate": "@file {name}",
    "doxdocgen.file.versionTag": "@version 1.0",
    "doxdocgen.generic.authorEmail": "fjdl@qq.com",
    "doxdocgen.generic.authorName": "shona",
    "doxdocgen.generic.authorTag": "@author {author} ({email})",
    // 日期格式与模板
    "doxdocgen.generic.dateFormat": "YYYY-MM-DD",
    "doxdocgen.generic.dateTemplate": "@date {date}",
    // 根据自动生成的注释模板（目前主要体现在函数注释上）
    "doxdocgen.generic.order": [
        "brief",
        "tparam",
        "param",
        "return"
    ],
    "doxdocgen.generic.paramTemplate": "@param{indent:8}{param}{indent:25}My Param doc",
    "doxdocgen.generic.returnTemplate": "@return {type} ",
    "doxdocgen.generic.splitCasingSmartText": true,
}

vscode安装插件koroFileHeader。

打开vscode settings(ctrl+shift+p, > setting搜索)，在settings中搜索Fileheader.cursorMode，选择编辑json，添加：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
"fileheader.customMade": { // 头部注释
    "Author": "Shona",
    "Date": "Do not edit",
    "LastEditors": "Shona",
    "LastEditTime": "Do not edit",
    "Description": "file content",
    "FilePath": "Do not edit" // 增加此项配置即可
},
"fileheader.cursorMode": { // 函数注释
    "description": "",
    "param": "params",
    "return": ""
},
"fileheader.configObj": {
    "autoAdd": true, // 默认开启自动添加头部注释，当文件没有设置头部注释时保存会自动添加
    "autoAlready": true, // 默认开启
    "prohibitAutoAdd": [
        "json",
        "md"
    ], // 禁止.json .md文件，自动添加头部注释
    "wideSame": false, // 设置为true开启
    "wideNum": 13 // 字段长度 默认为13
}

如果没有开启自动添加(“autoAdd”: false)，使用快捷键添加:

linux: ctrl+super+i
win: ctrl+alt+t

1
2
3
4
5
6
7
8
/*
 * @Author: Shona
 * @Date: 2021-12-24 15:09:58
 * @LastEditors: Shona
 * @LastEditTime: 2021-12-28 10:18:02
 * @Description: file content
 * @FilePath: a.cpp
 */

注意：团队使用时，需要所有人都在vscode上配置一样的格式，自己的名字，这样才会有效使用。