前言
程序中註釋的規範和統一性的重要性不言而喻,本文就推薦一種在用vscode編寫代碼時自動化生成標準化註釋格式的方法,關於Doxygen規範及其使用可查看博文 代碼註釋規範之Doxygen。html
本方法僅做爲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);