前言

​ 程序中注释的规范和统一性的重要性不言而喻，本文就推荐一种在用vscode编写代码时自动化生成标准化注释格式的方法，关于Doxygen规范及其使用可查看博文 代码注释规范之Doxygen。

​ 本方法仅作为Doxygen注释的辅助作用。

Vs code自动生成Doxygen格式注释

环境

• Vs code
• Generate Doxygen Comments 插件

Generate Doxygen Comments 插件使用及配置

安装插件后，File--Preferences--Settings-- 中打开用户 setting.json文件

初步设置后如下所示：

{
    "window.zoomLevel": 0,
    "editor.minimap.enabled": false,
    "python.pythonPath": "C:\\Users\\jordan\\AppData\\Local\\Programs\\Python\\Python37\\python.exe",
    "workbench.iconTheme": "vscode-icons",
    "explorer.autoReveal": false,   //取消左侧自动聚焦
    "terminal.integrated.shell.windows": "D:\\Program Files\\Git\\bin\\bash.exe",
    "terminal.external.windowsExec": "D:\\Program Files\\Git\\bin\\bash.exe",
    "todo-tree.highlights.enabled": true,

    // 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>wangh     <td>内容",
        "</table>",
    ],
    "doxdocgen.file.fileOrder": [
        "file",
        "brief",
        "author",
        "version",
        "date",
        "empty",
        "copyright",
        "empty",
        "custom"
    ],
    "doxdocgen.file.fileTemplate": "@file {name}",
    "doxdocgen.file.versionTag": "@version 1.0",
    "doxdocgen.generic.authorEmail": "wanghuan3037@fiberhome.com",
    "doxdocgen.generic.authorName": "wangh",
    "doxdocgen.generic.authorTag": "@author {author} ({email})",

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

解释如下：

{
    // 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>wangh     <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": "wanghuan3037@fiberhome.com",
    "doxdocgen.generic.authorName": "wangh",
    "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,
}

效果如下：

当在文件头部输入 “/**” 后回车,效果如下：

/**
 * @file main.c
 * @brief 
 * @author wangh (xxxxxxx@fiberhome.com)
 * @version 1.0
 * @date 2019-11-17
 * 
 * @copyright Copyright (c) 2019  XX通信公司
 * 
 * @par 修改日志:
 * <table>
 * <tr><th>Date       <th>Version <th>Author  <th>Description
 * <tr><td>2019-11-17 <td>1.0     <td>wangh     <td>内容
 * </table>
 */

在函数上面 “/**” 后回车,效果如下：

/**
 * @brief 
 * @param  buffer           My Param doc
 * @param  len              My Param doc
 * @return int 
 */
int platform_oled_write(uint8_t *buffer, uint16_t len);