C/C++ Doxygen 注释规范与特殊标记详解
代码中的特殊注释标记
在软件开发过程中，使用特定的注释标记可以极大地提升代码的可读性和可维护性。以下是一些常用的特殊注释及其含义：
- NOTE: 用于标记需要特别注意的信息、提示或背景知识。
- TODO: 指示此处有待完成的任务或需要实现的功能。
- FIXME: 表明代码中存在已知的问题或错误，需要进行修复。
- XXX: 标记代码实现有待优化或可能存在潜在问题的地方。
- HACK: 用于注释临时的、非优雅的解决方案，通常是为解决燃眉之急而采取的权宜之计。
- BUG: 明确指出代码中存在的缺陷，需要修复。
重点关注的特殊注释
TODO, FIXME, 和 XXX 是最常用于团队协作和代码维护的标记。
- TODO: 表示有待添加或完善的功能。例如：
// TODO: Add error handling for file operations. - FIXME: 指出代码中存在错误或需要改进的地方。例如：
// FIXME: This algorithm is inefficient for large datasets. - XXX: 警告其他开发者注意代码中的潜在风险、复杂性或需要改进的实现方式。例如：
// XXX: Consider a more robust parsing method here.
正确使用这些标记有助于团队成员清晰地理解代码状态和未来的工作方向。
其他实用注释标记
- HACK/HACKER: 标记临时性的、非标准的解决方案。例如：
// HACK: Workaround for device compatibility issue. - OPTIMIZE/PERFORMANCE: 指出可能影响性能的代码段，需要进一步优化。
- BUG: 明确标注已知缺陷。例如：
// BUG: Off-by-one error in loop condition. - NOTE/NOTICE: 提供重要的提示或背景信息。
- REVIEW: 请求他人评审某段代码。
- DEPRECATED: 标记已废弃的代码，提示开发者不应继续使用。
- UNDONE/WIP (Work In Progress): 表明当前正在进行但尚未完成的工作。
Doxygen 注释规范 (C/C++)
Doxygen 是一个强大的文档生成工具，遵循其注释规范可以自动生成高质量的API文档。
注释块类型
- 块注释 (Block Comments):
/** ... */：适合注释一个代码片段或整个文件。/*! ... */：功能同上。/** ... */和/**************** ... ****************/风格均可用于文档化代码块。- 行注释 (Line Comments):
/// ...：注释后面的一行代码。//! ...：功能同上。- 尾注 (Trailing Comments):
/*!< ... */或/**< ... */：注释前面的一行代码。///< ...或//!< ...：功能同上。
文件注释
通常放置在文件的开头，提供文件级别的元信息。
/**
* @file MyFile.h
* @brief 文件简要描述
* @details 文件的详细描述，可以包含更多信息。
* @mainpage 项目主页描述
* @author 作者姓名
* @email 作者邮箱
* @version 版本号 (e.g., 1.0.0)
* @date 日期 (e.g., YYYY-MM-DD)
* @license 版权信息
* @copyright 版权所有者
*/
函数注释
用于描述函数的用途、参数、返回值等。
简洁版
/**
* @brief 函数的简短描述
*
* @param[in] paramName 参数说明 (输入参数)
* @param[out] paramName 参数说明 (输出参数)
* @param[in,out] paramName 参数说明 (输入输出参数)
* @return 返回值的说明
* @retval value 返回值 (e.g., 0 表示成功)
*/
详细版
/**
* @brief 函数简短描述
* @details 函数的详细说明，可以包含算法、注意事项等。
*
* @param paramName 参数说明
* @param paramName 参数说明
* @return 返回值说明
* @retval value 返回值说明
* @note 重要的注释或提示
* @attention 需要特别注意的事项
* @warning 潜在的危险或警告信息
* @exception ExceptionType 抛出的异常类型及其说明
*/
示例:
/**
* @brief 程序主入口函数
* @details 程序的起始点，处理命令行参数。
*
* @param[in] argc - 命令行参数数量
* @param[in] argv - 命令行参数字符串数组
* @return int - 返回程序退出状态码
* @retval 0 - 程序成功执行
* @retval 1 - 程序执行出错
* @note 这是一个示例函数
*/
int main(int argc, char* argv[]) {
// Function body
return 0;
}
Doxygen 命令关键字
| 命令 | 生成字段名 | 说明 |
|---|---|---|
| @see | 参考 (See also) | 链接到其他相关文档或代码。 |
| @class | 引用类 (Refers to class) | 在文档中引用类。 |
| @var | 引用变量 (Refers to variable) | 在文档中引用变量。 |
| @enum | 引用枚举 (Refers to enum) | 在文档中引用枚举。 |
| @code | 代码块开始 (Start code block) | 标记代码块的开始，与 @endcode 成对使用。 |
| @endcode | 代码块结束 (End code block) | 标记代码块的结束。 |
| @bug | 缺陷 (Bug) | 链接到所有缺陷汇总列表。 |
| @todo | TODO | 链接到所有 TODO 列表。 |
| @example | 使用示例 (Example usage) | 提供代码使用示例。 |
| @remarks | 备注 (Remarks) | 添加额外的备注信息。 |
| @pre | 前置条件 (Precondition) | 描述函数执行前的先决条件。 |
| @deprecated | 已弃用 (Deprecated) | 标记已弃用的函数或类，并说明原因。 |
类型定义、宏、枚举、结构体注释
/**
* @brief 定义一个2字节的无符号字符类型。
*/
typedef unsigned short WORD;
/// @brief 定义一个缓存大小宏。
#define BUFFER_SIZE 1024*4 ///< 缓存大小
/**
* @brief 枚举类型，表示颜色。
*/
enum Color {
RED = 0, ///< 红色
GREEN = 1, ///< 绿色
YELLOW = 2 ///< 黄色
};
/**
* @brief 针清洗（灌注）参数结构体。
* @details 包含样本针或试剂针的ID和错误码。
*/
typedef __packed struct {
uint8_t needle_id; ///< 1: 样本针, 2: 试剂针
uint32_t error_code; ///< 错误码计数
} NeedleWashParams;
常量/变量注释
常量和变量的注释可以放在代码行的前面或后面。
代码前注释
/// @brief 全局配置选项的数量
const int CONFIG_OPTIONS_COUNT = 5;
代码后注释
#define MAX_CONNECTIONS 100 ///< 最大并发连接数
