Doxygen注释规范

第一章：注释说明

指令	说明
@file	文件名
@brief	简介说明
@author	作者信息
@date	创作日期，年-月-日
@version	版本号
@copyright	版权信息
@param	主要用于函数说明中，后面接参数的名字，然后再接关于该参数的说明
@return	描述该函数的返回值情况
@retval	描述返回值类型
@par	开始一个段落，段落名称描述由自己指定
@mainpage	主页信息
@note	注解
@attention	注意
@warning	警告信息
@enum	枚举，会在该枚举处产生一个链接
@var	引用变量，会在该枚举处产生一个链接
@class	声明类/引用某个类，格式：@class name [header-file] [header-name]
@exception	可能产生的异常描述
@todo	对将要做的事情进行注释
@see	参考，一段包含其他部分引用的注释，中间包含对其他代码项的名称，自动产生对其的引用链接
@relates	通常用做把非成员函数的注释文档包含在类的说明文档中
@since	通常用来说明从什么版本、时间写此部分代码
@code	在注释中开始说明一段代码，直到@endcode命令
@endcode	在注释中代码段的结束
@pre	用来说明代码项的前提条件
@post	用来说明代码项之后的使用条件
@defgroup	模块名
@fn	声明一个函数
@bug	漏洞
@details	细节
@link	连接
@throw	异常描述
@deprecated	弃用说明，可用于描述替代方案，预期寿命等
@example	弃用说明，可用于描述替代方案，预期寿命等

第二章：注释规范

2.1 文件注释

举例如下：

/**
* @file xxx.c
* @brief Discription of this file.
* @author xxx@abc.com
* @version 1.0
* @date 2023-12-07
* @copyright Copyright (c) cccc
*
* @par 修改日志
* <table>
* <tr><th>Date        <th>Version  <th>Author    <th>Description
* <tr><td>2023/12/07  <td>0.5      <td>xxx       <td>创建初始版本
* <tr><td>2023/12/08  <td>1.0      <td>xxx       <td>增加..更改..
* </table>
*/

生成示例：

2.2 函数注释

举例如下：

/**
 * @brief Discription of this function
 * 
 * @param  name Description of parameter1
 * @param  number Description of parameter2
 * @return int 
 */
int student_grades (char name,int number);

生成示例：

2.3 结构体/枚举注释

举例如下：

/**  学生结构体 */
struct Student {
	char name;///< 学生姓名
	int number;///< 学生学号
} Str_Student;

生成示例：

2.4 宏定义/单行注释

举例如下：

#define ADDRESS (0x20000000) ///< address

生成示例：

2.5 组定义

举例如下：

/**
 * @defgroup 定义log的级别
 * @{
 */
#define A_LEVEL 0 ///< A_LEVEL 
#define B_LEVEL 1 ///< B_LEVEL 
#define C_LEVEL 2 ///< C_LEVEL 
#define D_LEVEL 3 ///< D_LEVEL 
/**
 * @}
 */

生成示例：

第三章：注释使用

在VS Code软件中增加doxygen规范注释，比较方便。有以下2种方式可以进行增加注释，可以单独使用其中一种，也可以2种结合起来使用。

3.1 Doxygen Documentation Generator 插件

1. 安装插件：在VS Code的扩展种搜索 Doxygen Documentation Generator ，下载安装；
2. 自定义设置：文件—>首选项—>设置（快捷键ctrl+,）；用户—>扩展—>Doxygen Documentation Generator Settings—>settings.json文件，打开文件进行自定义设置；
3. 自定义设置举例：json文件如下

{
    "editor.accessibilitySupport": "on",
    "editor.unicodeHighlight.nonBasicASCII": false,
    "editor.fontLigatures": false,
    "editor.fontSize": 16,
    "terminal.integrated.profiles.windows": {
        "my-pwsh": {
            "source": "PowerShell",
            "args": [
                "-NoProfile"
            ]
        }
    },
    "terminal.integrated.defaultProfile.windows": "my-pwsh",
    "files.autoGuessEncoding": true,
    "workbench.colorTheme": "Default Dark+",
    "cmake.configureOnOpen": true,
    "security.workspace.trust.untrustedFiles": "open",
    "editor.minimap.enabled": false,
    // 文件注释，版权模块
    "doxdocgen.file.copyrightTag": [
        "@copyright Copyright (c) {year} 公司名称版权啊."
    ],
    // 文件注释，以及排序
    "doxdocgen.file.fileOrder":[
        "file",
        "author",
        "brief",
        "version",
        "date",
        "empty",
        "copyright",
        "empty"
    ],
    // 下面时设置上面标签tag的具体信息
    "doxdocgen.file.fileTemplate": "@file {name}",
    "doxdocgen.file.versionTag": "@version 1.0",
    "doxdocgen.generic.authorEmail": "@qq.com",
    "doxdocgen.generic.authorName": "xxx",
    "doxdocgen.generic.authorTag": "@author {author}{email}",
    // 日期格式与模板
    "doxdocgen.generic.dateFormat": "YYYY-MM-DD",
    "doxdocgen.generic.dateTemplate": "@date {date}",
    // 函数（通用）注释模块
    "doxdocgen.generic.order": [
        "brief",
        "empty",
        "tparam",
        "param",
        "return"
    ],
    "doxdocgen.generic.paramTemplate": "@param{indent:8}{param}{indent:5}",
    "doxdocgen.generic.returnTemplate": "@return {type} ",
    "doxdocgen.generic.splitCasingSmartText": true,
    "Codegeex.Comment.LanguagePreference": "中文",
    "Codegeex.Privacy": true,
}

4. 使用：在需要增加注释的地方，输入" /** + 回车" 即可。

3.2 代码片段的使用

1. 代码片段的路径：文件—>首选项—>配置用户代码片段（快捷键Ctrl + Shift + P）
   
   已有代码片段的直接选择“现有代码片段”，无则选择“新代码片段”。
2. 代码片段基本语法：创建新代码片段后，会有举例说明如下：

{
	// Place your 全局 snippets here. Each snippet is defined under a snippet name and has a scope, prefix, body and 
	// description. Add comma separated ids of the languages where the snippet is applicable in the scope field. If scope 
	// is left empty or omitted, the snippet gets applied to all languages. The prefix is what is 
	// used to trigger the snippet and the body will be expanded and inserted. Possible variables are: 
	// $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders. 
	// Placeholders with the same ids are connected.
	// Example:
	// "Print to console": {
	// 	"scope": "javascript,typescript",
	// 	"prefix": "log",
	// 	"body": [
	// 		"console.log('$1');",
	// 		"$2"
	// 	],
	// 	"description": "Log output to console"
	// }
}

如文件注释即可写为：

{
	"add file note": {
		"scope": "c,cpp",
		"prefix": [ "header", "fileheader"],
		"body": [
			"/**",
 			" * @file ${TM_FILENAME}",
			" * @author ${1:xxx@qq.com}",
			" * @brief ${2:Discription of this file.}",
			" * @version 1.0",
			" * @date ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}",
			" *",
			" * @copyright ${3:Copyright (c)} ${CURRENT_YEAR} ccc",
			" *",
			" */"
		],
		"description": "Adds copyright..."
	}
}

scope ---- 指定特定的语言类型，可以使用逗号来分割多种语言。
prefix ---- 触发文本，可以是一个字符串或者一个字符串数组。
body ---- 插入片段的内容
description ---- 代码片段的更多描述
3. 使用：在需要插入注释的位置输入自定义的prefix + 回车，如上面文件注释输入" header + 回车 " 即可。