代码注释指南

版本：v0.1（初版，仅含 @defgroup 分组规范，后续补充完整注释规范）

本指南规定 xt-sdk 源码（头文件/源文件）的 doxygen 注释写法，属于 T1 文档范畴。配套阅读：文档准确度原则。

---

一、doxygen 分组：@defgroup + @name

组件头文件（<组件名>.h）用 @defgroup 创建模块分组，用 @name 在组内划分子分区。

1.1 标准模板

/**
 * @defgroup xt_xxx <组件中文名>
 * @brief <一句话简介>
 * @ingroup xt_components
 * @{
 */
 
/* === 用户 API === */
 
/**
 * @name 生命周期
 * @{
 */
xt_xxx_err_t xt_xxx_init(const xt_xxx_config_t *cfg);
/** @} */  /* 生命周期 */
 
/**
 * @name 文件读写
 * @{
 */
xt_xxx_ssize_t xt_xxx_read(xt_xxx_handle_t h, void *buf, xt_xxx_size_t n);
/** @} */  /* 文件读写 */
 
/**
 * @defgroup xt_xxx__dev 开发者接口
 * @ingroup xt_xxx
 * @brief 后端对接、移植相关接口
 * @{
 */
/* 后端对接接口（ops、port 等） */
/** @} */  /* xt_xxx__dev */
 
/** @} */  /* xt_xxx */

1.2 规则

规则	说明
顶级组声明	用 @defgroup xt_xxx，通过 @ingroup xt_components（或 xtiny 接口）挂到父组
开发者接口子组	命名为 xt_xxx__dev（双下划线后缀），@ingroup xt_xxx
函数子分区	用 @name "分区名"（如生命周期、文件读写、目录操作）
组闭合	用**单行** /** @} */ /* 组名 */，不用多行 End of xxx
追加内容	@defgroup 用于首次声明，@addtogroup 用于向已有组追加内容
无总头文件的组	定义在组件旁的 .dox 文件中（参见 components/xt_components.dox）

1.3 参考示例

以下头文件是已落地的 @defgroup 打样，新增组件时请参考其结构：

• components/xt_vfs/xt_vfs.h — 单组件，含 @name 子分区 + xt_vfs__dev 开发者组
• components/xt_task/xt_task.h — 带 @name 分区
• platforms/components/xtiny/xt_log/xt_log.h — xtiny 模块，多 @name 分区
• components/xt_components.dox — 顶级组 公共组件 声明（无总头文件的情况）

---

待补充

本指南为初版，以下章节后续补充：

• 函数注释规范（@param、@return、@note、@warning 等）
• 结构体/枚举/宏注释规范
• @code 示例块写法
• 文件头注释（SPDX、文件说明）
• @deprecated 标注规范