二、Doxygen注释规范（C/C++）
一、妙用代码中特殊注释——TODO、FIXME、XXX、HACK、BUG、NOTE
注释格式说明
# NOTE:
用于标记需要注意的地方，如重要信息、提示等
# TODO:
用于标记待办事项，提醒开发者需要完成的任务
# FIXME:
用于标记需要修复的问题，通常是在代码中已知的错误或需要改进的地方
# XXX:
用于标记代码中需要优化的地方，可能是一些潜在的问题或需要注意的细节
# HACK:
用于标记一些临时的、不太优雅的解决方案，通常是为了快速解决问题而采取的权宜之计
# BUG:
用于标记已知的bug，提醒开发者需要修复
1.1 最常用的三种特殊注释：
TODO表示待完成的功能，FIXME表明代码需要修正或存在错误，XXX则用于标记待优化的实现。这三种注释为团队协作和代码维护提供了清晰的指南
TODO - 待办事项。
TODO表示这里有待完成的任务或者待实现的功能。如果代码中有该标识，说明在标识处有功能代码待编写，待实现的功能在说明中会简略说明。
No problem, but addtional code needs to be written (usually when you are skipping something)情未了
FIXME - 待修理或存在问题。指出代码中存在问题或bug，需要修复的地方。如果代码中有该标识，说明标识处代码需要修正，甚至代码是错误的，不能工作，需要修复，如何修正会在说明中简略说明。This works, sort of, but it could be done better. (usually code written in a hurry that needs rewriting) Fuck Me
XXX - 待优化的实现表示代码可能包含临时解决方案、糟糕的实践、或者有待优化的部分，通常意味着此处的实现方式并不理想，应在未来重新审视和改进。如果代码中有该标识，说明标识处代码虽然实现了功能，但是实现的方法有待商榷，希望将来能改进，要改进的地方会在说明中简略说明。Warning about possible pitfalls, can be used as NOTE:XXX:陷阱
总结起来，代码注释中的 TODO、FIXME、XXX 是三种不同层次、不同紧迫程度的代码标记。
TODO 提示未来添加或完善的功能，
FIXME 指出需要尽快解决的问题，
XXX 警告其他开发人员注意代码中的潜在风险或复杂性。
这些标记的正确使用，有助于开发团队更高效地协作和管理代码。
1.2 其他注释：
HACK 或 HACKER - 临时方案标记一段临时性的、非常规的解决方案，通常用于应对紧急问题，但长期来看不是最优解。英语翻译为砍。如果代码中有该标识，说明标识处代码我们需要根据自己的需求去调整程序代码。Not very well written or malformed code to circumvent a problem/bug. Should be used as HACK:FIXME:补锅踩雷填坑
OPTIMIZE 或 PERFORMANCE - 性能攸关标记可能影响性能的地方，需要进一步优化。
BUG - 故障 There is a problem here.丢锅埋雷挖坑
NOTE 或 NOTICE - 提示提供一些重要提示或背景信息。escription of how the code works (when it isn’t self evident) 汝等凡人
REVIEW - 待评审请求他人复查某段代码，可能是为了确认设计决策、逻辑是否正确或改进代码质量。
DEPRECATED - 废弃标记已弃用的代码，提醒开发者这段代码未来可能会被移除。
UNDONE 或 WIP (Work In Progress) - 进行中未完成
标记正在进行的工作，表明这部分代码尚未完成。
二、Doxygen注释规范（C/C++）
链接：Doxygen中文手册
2.1 块注释
片段注释（代码前注释，解释后面一/多段）
/**
*
* …… 适合一个片段
*
*//************************************************ * …… 适合分割多个片段 * ************************************************/
行注释（代码前注释，解释后面一行）
///…
/** …… *
批注（代码后注释，解释前面一行）
/*!< ... 批注 ... */
/**< ... 批注 ... */ （推荐）
//!< ... 批注 ...
///< ... 批注 ... （推荐）
2.2 文件注释
/**
* @file 文件名
* @brief 简介
* @details 细节
* @mainpage 工程概览
* @author 作者
* @email 邮箱
* @version 版本号
* @date 年-月-日
* @license 版权 * @copyright Apple Inc.
*/
e.g.
/**
* @file Test.h
* @brief 测试头文件
* @details 这个是测试Doxygen
* @mainpage 工程概览
* @author SunTroop
* @email suntroop@sina.com
* @version 1.0.0
* @date 2017-11-17
*/
2.3 函数注释
简约版
/**
* @brief 函数简介
*
* @param[in] 形参 - 参数说明
* @param[out] 形参 - 参数说明
* @param[in,out] 形参 - 参数说明
* @return 返回说明
* @retval 返回值 - 说明
*/
详细版
/**
* @brief 函数简介
* @detail 详细说明
*
* @param 形参 参数说明
* @param 形参 参数说明
* @return 返回说明
* @retval 返回值说明
* @note 注解
* @attention 注意
* @warning 警告
* @exception 异常
*/
e.g.
/**
* @brief 主函数
* @details 程序唯一入口
*
* @param[in] argc - 命令参数个数
* @param[in] argv - 命令参数指针数组
* @return 程序执行成功与否
* @retval 0 - 程序执行成功
* @retval 1 - 程序执行失败
* @note 这里只是一个简单的例子
*/
int main(int argc, char* argv[])
下面一些标注方式可以根据需要选择使用。
Doxygen 命令关键字
命令
生成字段名
说明
@see
参考
@class
引用类
用于文档生成连接
@var
引用变量
用于文档生成连接
@enum
引用枚举
用于文档生成连接
@code
代码块开始
与@endcode成对使用
@endcode
代码块结束
与@code成对使用
@bug
缺陷
链接到所有缺陷汇总的缺陷列表
@todo
TODO
链接到所有TODO 汇总的TODO 列表
@example
使用例子说明
@remarks
备注说明
@pre
函数前置条件
@deprecated
函数过时说明
2.4 类型/宏定义/枚举/结构·注释
/**
* 2字节字符类型
*/
typedef unsigned short WORD;
/// 缓存大小
#define BUFSIZ 1024*4 ///< 缓存大小
/** 枚举类型*/
enum COLOR{
RED=0, ///< 红色
GREEN=1, ///< 绿色
YELLOW=2 ///< 黄色
};
/// 针清洗（灌注）参数
typedef __packed struct
{
U8 id; ///< 1：样本针 2：试剂针
U32 errCode; ///< 次数
}NEEDLE_CLEAN_BACK;
2.5 常量/变量·注释
代码前注释·格式
/// 注释
常量/变量
e.g.
/// 缓存大小
#define BUFSIZ 1024*4
代码后注释·格式
常量/变量 ///< 注释
e.g.
#define BUFSIZ 1024*4 ///< 缓存大小