前言

本文推荐一种在用vscode编写代码时自动化生成标准化注释格式的方法。

插件名字：Doxygen Documentation Generator

插件使用说明：

https://github.com/cschlosser/doxdocgen

使用说明

  • 在 vscode 扩展商城中搜索 Doxygen Documentation Generator
  • 打开vscode settings.json(快捷键CTRL+P, 输入: > setings, 选择: 打开用户设置 ), 对插件进行配置
  • 在代码首行或者函数前面输入 /** 后，按下 Enter即可自动生成注释

setting.json 配置模板

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
47
48
49
50
51
52
53
  // /**回车后最多向下多少行去找函数声明
"doxdocgen.generic.linesToGet": 10,
  // 作者名和邮箱
  "doxdocgen.generic.authorTag": "@author{indent:13}: stone (39035605@qq.com)",
  // 日期格式
  "doxdocgen.generic.dateFormat": "YYYY-MM-DD",
  "doxdocgen.generic.dateTemplate": "@date{indent:13}: {date}",
  // 简介格式
  "doxdocgen.generic.briefTemplate": "@brief{indent:13}: ",

  "doxdocgen.generic.generateSmartText": true,
  "doxdocgen.generic.splitCasingSmartText": true,


  // 文件注释的格式
  "doxdocgen.file.fileTemplate": "@file{indent:13}: {name}",
  "doxdocgen.file.versionTag": "@version{indent:13}: 1.0",
  "doxdocgen.file.copyrightTag": [
      "@copyright{indent:13}: Copyright (c) {year} stone (39035605@qq.com)"
  ],
  
  // 自定义文件注释格式
  "doxdocgen.file.customTag": [
      "",
      "@revision history:",
      "{indent:10}{date} - Initial version."
  ],
  // 文件注释组成及顺序
  "doxdocgen.file.fileOrder": [
      "copyright",// 版权
      "empty",	// 空行
      "file",		// @file
      "brief",	// @brief 简介
      "author",	// 作者
      "date",		// 日期
      "version",	// 版本
      "empty",	// 空行
      "custom"	// 自定义
  ],

  // 参数注释和返回注释的格式
  "doxdocgen.generic.paramTemplate": "@param{indent:13}: {param}{indent:25}",
  //  "doxdocgen.generic.returnTemplate": "@return\t\t :{type}{indent:20}",
  "doxdocgen.generic.returnTemplate": "@return{indent:13}: {type}{indent:25}",
  // 函数注释组成及顺序
  "doxdocgen.generic.order": [
      "brief",
      "empty",	// 空行
      "tparam",
      "param",
      "empty",	// 空行
      "return"
  ],

官方配置选项说明

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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
{
  // The prefix that is used for each comment line except for first and last.
  "doxdocgen.c.commentPrefix": " * ",

  // Smart text snippet for factory methods/functions.
  "doxdocgen.c.factoryMethodText": "Create a {name} object",

  // The first line of the comment that gets generated. If empty it won't get generated at all.
  "doxdocgen.c.firstLine": "/**",

  // Smart text snippet for getters.
  "doxdocgen.c.getterText": "Get the {name} object",

  // The last line of the comment that gets generated. If empty it won't get generated at all.
  "doxdocgen.c.lastLine": " */",

  // Smart text snippet for setters.
  "doxdocgen.c.setterText": "Set the {name} object",

  // Doxygen comment trigger. This character sequence triggers generation of Doxygen comments.
  "doxdocgen.c.triggerSequence": "/**",

  // Smart text snippet for constructors.
  "doxdocgen.cpp.ctorText": "Construct a new {name} object",

  // Smart text snippet for destructors.
  "doxdocgen.cpp.dtorText": "Destroy the {name} object",

  // The template of the template parameter Doxygen line(s) that are generated. If empty it won't get generated at all.
  "doxdocgen.cpp.tparamTemplate": "@tparam {param} ",

  // 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. One tag per line will be added. Can template `{year}`, `{date}`, `{author}`, `{email}` and `{file}`. You have to specify the prefix.
  "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": "you@domain.com",

  // 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})",

  // If this is enabled a bool return value will be split into true and false return param.
  "doxdocgen.generic.boolReturnsTrueFalse": true,

  // 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}",

  // Decide if you want to get smart text for certain commands.
  "doxdocgen.generic.generateSmartText": true,

  // Whether include type information at return.
  "doxdocgen.generic.includeTypeAtReturn": true,

  // How many lines the plugin should look for to find the end of the declaration. Please be aware that setting this value too low could improve the speed of comment generation by a very slim margin but the plugin also may not correctly detect all declarations or definitions anymore.
  "doxdocgen.generic.linesToGet": 20,

  // 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",
    "version",
    "author",
    "date",
    "copyright"
  ],

  // Custom tags to be added to the generic order. One tag per line will be added. Can template `{year}`, `{date}`, `{author}`, `{email}` and `{file}`. You have to specify the prefix.
  "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,

  // Array of keywords that should be removed from the input prior to parsing.
  "doxdocgen.generic.filteredKeywords": [],

  // Substitute {author} with git config --get user.name.
  "doxdocgen.generic.useGitUserName": false,

  // Substitute {email} with git config --get user.email.
  "doxdocgen.generic.useGitUserEmail": false,

  // Provide intellisense and snippet for doxygen commands
  "doxdocgen.generic.commandSuggestion": true,

  // Add `\\` in doxygen command suggestion for better readability (need to enable commandSuggestion)
  "doxdocgen.generic.commandSuggestionAddPrefix": false,
}