參考
谷歌項目風格指南——注釋
C++ doxygen 風格注釋示例
ubuntu20 中 doxygen 文檔生成
doxygen 官方文檔 在 /Doxygen/Special Command/ 章節介紹 doxygen 的關鍵字
注釋說明
注釋的目的是提高代碼的可讀性與可維護性。
C 風格注釋
// 單行注釋/*
多行注釋
*/C ++ 風格注釋：
/// 單行注釋
//! 單行注釋/**
多行注釋
*/
/*!
多行注釋
*/-
文件注釋：時間 + 版權 + 維護作者 + 文件內容
-
類注釋：類的功能 + 用法 + 注意事項
-
函數注釋：
??函數聲明通常位于頭文件，頭文件是客戶使用函數服務的窗口。在函數聲明處需要注釋函數功能，解釋接口，調用規則，潛在風險等，以避免函數使用不當；
??函數定義通常位于源文件，源文件是程序員維護，實現功能的平臺。比喻作平臺是因為服務端功能實現可以是由多個程序員共同維護的，注釋要注重功能理解以降低代碼維護成本。在函數定義處需要注釋功能實現細節，編程技巧，算法原理，詳細文檔資料位置等。
??不要重復函數聲明和定義的注釋，沒有意義！
-
變量注釋：
??成員變量和局部變量：除了簡單的變量，都要說明變量的定義和用途。尤其是定義解釋至關重要，避免變量被濫用導致歧義！有特定值的變量需要強調特定值。
??全局變量：每個全局變量都要說明定義和用途。
-
實現注釋：對巧妙, 晦澀, 重要的地方加以注釋。解釋代碼段功能或為什么這么處理。
-
TODO注釋：對臨時方案，不好的代碼注釋方便日后改進。
-
棄用注釋：在棄用代碼上方加
// deprecate：棄用說明。棄用代碼最好用//屏蔽，方便搜索欄發現代碼已棄用。
Utuntu20 Vscode Doxygen 自動生成文檔
vscode 安裝 doxygen documentation generator 插件，在插件的商店頁面，點擊導航欄的 Config options 可以跳轉到 json 配置說明位置。
安裝好插件后，在文件頭和函數頭部打/**回車，就會生成注釋。
在 vscode 按 ctrl+shift+p，搜索 “settings”，選擇首選項配置（JSON）配置 doxygen 參數。
粘貼下面配置：
// ---------- doxygen 注釋配置 ---------- start line"doxdocgen.c.triggerSequence": "/**", // 觸發 doxygen 注釋"doxdocgen.c.commentPrefix": " * ", // 中間注釋行的前綴"doxdocgen.c.firstLine": "/**", // 注釋首行"doxdocgen.c.lastLine": " */", // 注釋尾行"doxdocgen.generic.authorName": "jucat","doxdocgen.generic.authorEmail": "lmr2887@163.com","doxdocgen.generic.authorTag": "@author {author} ({email})","doxdocgen.generic.dateFormat": "YYYY-MM-DD","doxdocgen.generic.dateTemplate": "@date {date}","doxdocgen.generic.generateSmartText": false,"doxdocgen.generic.boolReturnsTrueFalse": true,"doxdocgen.generic.briefTemplate": "@brief {text}","doxdocgen.generic.includeTypeAtReturn": true,"doxdocgen.generic.linesToGet": 20,"doxdocgen.generic.customTags": [],"doxdocgen.generic.paramTemplate": "@param {param} ","doxdocgen.generic.returnTemplate": "@return {type} ","doxdocgen.generic.splitCasingSmartText": true,"doxdocgen.generic.filteredKeywords": [],"doxdocgen.generic.useGitUserName": false,"doxdocgen.generic.useGitUserEmail": false,"doxdocgen.generic.commandSuggestion": true,"doxdocgen.generic.commandSuggestionAddPrefix": false,// 文件頭部注釋"doxdocgen.file.copyrightTag": ["@copyright Copyright (c) {year} jucat"],"doxdocgen.file.versionTag": "@version 0.1","doxdocgen.file.fileTemplate": "@file {name}","doxdocgen.file.fileOrder": ["file","author","email","brief","version","date","empty","copyright","empty","custom"],// 自動生成的函數注釋模板，不區分源文件和頭文件"doxdocgen.generic.order": ["brief","tparam","param","return"],// 自定義注釋模塊"doxdocgen.file.customTag": ["@par 修改日志:","<table>","<tr><th>Date <th>Version <th>Author <th>Description","<tr><td>{date} <td>1.0 <td>wangh <td>內容","</table>",],// ---------- doxygen 注釋配置 ---------- end line文檔生成
安裝 doxygen-gui ：
sudo apt install doxygen-gui終端執行命令：
doxywizarddoxygen-gui 配置：
運行完成后，在 “文檔輸出位置” 目錄下的 files.html 文件就是代碼項目文檔。
點擊 類 -> 類列表 ，再點擊查看類詳細說明。
源文件注釋：
頭文件注釋：
?文檔效果：
更多 doxygen 關鍵字參考文章開頭的“參考”，文檔效果就自己測試看看了。
-Rules 8.11)
