Vs code自動生成Doxygen格式註釋

前言

​ 程序中註釋的規範和統一性的重要性不言而喻,本文就推薦一種在用vscode編寫代碼時自動化生成標準化註釋格式的方法,關於Doxygen規範及其使用可查看博文 代碼註釋規範之Doxygenhtml

​ 本方法僅做爲Doxygen註釋的輔助做用。python

Vs code自動生成Doxygen格式註釋

環境shell

  • Vs code
  • Generate Doxygen Comments 插件

Generate Doxygen Comments 插件使用及配置json

安裝插件後,File--Preferences--Settings-- 中打開用戶 setting.json文件windows

初步設置後以下所示:bash

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

效果以下:ui

當在文件頭部輸入 「/**」 後回車,效果以下:spa

/**
 * @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);
相關文章
相關標籤/搜索