前言
程序中注释的规范和统一性的重要性不言而喻，本文就推荐一种在用vscode编写代码时自动化生成标准化注释格式的方法，关于Doxygen规范及其使用可查看博文 代码注释规范之Doxygen。
本方法仅作为Doxygen注释的辅助作用。
Vs code自动生成Doxygen格式注释
环境
- Vs code
- Generate Doxygen Comments 插件
Generate Doxygen Comments 插件使用及配置
安装插件后，File--Preferences--Settings-- 中打开用户 setting.json文件
初步设置后如下所示：
1{ 2 "window.zoomLevel": 0, 3 "editor.minimap.enabled": false, 4 "python.pythonPath": "C:\\Users\\jordan\\AppData\\Local\\Programs\\Python\\Python37\\python.exe", 5 "workbench.iconTheme": "vscode-icons", 6 "explorer.autoReveal": false, //取消左侧自动聚焦 7 "terminal.integrated.shell.windows": "D:\\Program Files\\Git\\bin\\bash.exe", 8 "terminal.external.windowsExec": "D:\\Program Files\\Git\\bin\\bash.exe", 9 "todo-tree.highlights.enabled": true, 10 11 // Doxygen documentation generator set 12 "doxdocgen.file.copyrightTag": [ 13 "@copyright Copyright (c) {year} XX通信公司" 14 ], 15 "doxdocgen.file.customTag": [ 16 "@par 修改日志:", 17 "<table>", 18 "<tr><th>Date <th>Version <th>Author <th>Description", 19 "<tr><td>{date} <td>1.0 <td>wangh <td>内容", 20 "</table>", 21 ], 22 "doxdocgen.file.fileOrder": [ 23 "file", 24 "brief", 25 "author", 26 "version", 27 "date", 28 "empty", 29 "copyright", 30 "empty", 31 "custom" 32 ], 33 "doxdocgen.file.fileTemplate": "@file {name}", 34 "doxdocgen.file.versionTag": "@version 1.0", 35 "doxdocgen.generic.authorEmail": "wanghuan3037@fiberhome.com", 36 "doxdocgen.generic.authorName": "wangh", 37 "doxdocgen.generic.authorTag": "@author {author} ({email})", 38 39 "doxdocgen.generic.order": [ 40 "brief", 41 "tparam", 42 "param", 43 "return" 44 ], 45 "doxdocgen.generic.paramTemplate": "@param{indent:8}{param}{indent:25}My Param doc", 46 "doxdocgen.generic.returnTemplate": "@return {type} ", 47 "doxdocgen.generic.splitCasingSmartText": true, 48}
解释如下：
1{ 2 // Doxygen documentation generator set 3 // 文件注释：版权信息模板 4 "doxdocgen.file.copyrightTag": [ 5 "@copyright Copyright (c) {year} XX通信公司" 6 ], 7 // 文件注释：自定义模块，这里我添加一个修改日志 8 "doxdocgen.file.customTag": [ 9 "@par 修改日志:", 10 "<table>", 11 "<tr><th>Date <th>Version <th>Author <th>Description", 12 "<tr><td>{date} <td>1.0 <td>wangh <td>内容", 13 "</table>", 14 ], 15 // 文件注释的组成及其排序 16 "doxdocgen.file.fileOrder": [ 17 "file", // @file 18 "brief", // @brief 简介 19 "author", // 作者 20 "version", // 版本 21 "date", // 日期 22 "empty", // 空行 23 "copyright",// 版权 24 "empty", 25 "custom" // 自定义 26 ], 27 // 下面时设置上面标签tag的具体信息 28 "doxdocgen.file.fileTemplate": "@file {name}", 29 "doxdocgen.file.versionTag": "@version 1.0", 30 "doxdocgen.generic.authorEmail": "wanghuan3037@fiberhome.com", 31 "doxdocgen.generic.authorName": "wangh", 32 "doxdocgen.generic.authorTag": "@author {author} ({email})", 33 // 日期格式与模板 34 "doxdocgen.generic.dateFormat": "YYYY-MM-DD", 35 "doxdocgen.generic.dateTemplate": "@date {date}", 36 37 // 根据自动生成的注释模板（目前主要体现在函数注释上） 38 "doxdocgen.generic.order": [ 39 "brief", 40 "tparam", 41 "param", 42 "return" 43 ], 44 "doxdocgen.generic.paramTemplate": "@param{indent:8}{param}{indent:25}My Param doc", 45 "doxdocgen.generic.returnTemplate": "@return {type} ", 46 "doxdocgen.generic.splitCasingSmartText": true, 47}
效果如下：
当在文件头部输入 “/**” 后回车,效果如下：
1/** 2 * @file main.c 3 * @brief 4 * @author wangh (xxxxxxx@fiberhome.com) 5 * @version 1.0 6 * @date 2019-11-17 7 * 8 * @copyright Copyright (c) 2019 XX通信公司 9 * 10 * @par 修改日志: 11 * <table> 12 * <tr><th>Date <th>Version <th>Author <th>Description 13 * <tr><td>2019-11-17 <td>1.0 <td>wangh <td>内容 14 * </table> 15 */
在函数上面 “/**” 后回车,效果如下：
1/** 2 * @brief 3 * @param buffer My Param doc 4 * @param len My Param doc 5 * @return int 6 */ 7int platform_oled_write(uint8_t *buffer, uint16_t len);