Vs code自動生成Doxygen格式注釋

前言

​ 程序中注釋的規范和統一性的重要性不言而喻，本文就推薦一種在用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": "[e-mail]",
    "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": "[e-mail]",
    "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 ([e-mail])
 * @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);