doxygen 注释命令

### Doxygen 注释语法概述

Doxygen 支持多种风格的注释来标记代码中的不同部分，从而可以自动生成高质量的技术文档。对于注释块的位置，实际上支持将其放置于几乎任何地方（除了函数体内或普通的 C 注释内）[^4]。

#### 基本注释样式

有三种基本方式用于创建 Doxygen 可识别的注释：

- 使用 `/** ... */` 或者 `/*! ... */` 来定义多行注释。
- 单行注释可以通过在前面加上额外的星号(`*`)或者感叹号(`!`)实现，即 `///` 或者 `//!`.

/**
 * 这是一个简单的例子，
 * 展示了如何编写一个多行注释。
 */
void exampleFunction() {}

/// 这是一条单行注释的例子。
int singleLineCommentExample;

#### 函数与成员变量注释

当涉及到为函数或类成员添加描述时，通常会在它们之前加入详细的解释文字，并利用特定标签提供更丰富的信息。例如，在声明一个函数前使用如下格式[^2]:

/**
 * @brief 计算两个整数的最大公约数.
 *
 * 此方法实现了欧几里得算法以求解最大公因数。
 *
 * @param a 第一个输入参数
 * @param b 第二个输入参数
 * @return 返回a和b之间的最大公约数
 */
int gcd(int a, int b);

#### 枚举类型注释

枚举类型的处理类似于类，可以在其定义前后添加适当的信息帮助理解各个枚举项的意义。下面是如何给定一段带有注释的枚举定义:

/// 定义颜色选项列表
enum Color {
    BLACK, ///< 黑色表示无光状态
    WHITE  ///< 白色代表全反射特性
};

#### 特殊命令

为了增强生成文档的功能性和易读性，Doxygen 提供了一系列特殊的命令，比如:

- `\file`: 描述整个文件的作用；
- `\mainpage`: 创建主页内容；
- `\section`, `\subsection`: 组织大篇幅的文字材料；
- `\warning`, `\note`, `\todo`: 添加警告、提示以及待办事项等辅助说明；

通过合理运用上述提到的各种注释技巧及内置指令，开发者不仅可以让自己的源码更加清晰明了，同时也简化了维护过程中所需的工作量[^3].