Doxygen注释风格

Doxygen 是一种从源代码中自动抽取注释生成文档的工具，支持 C/C++、Java、Python 等多种语言。

一、最常用标签（C/C++ 版）

标签	含义	出现位置	备注
`@brief`	一句话功能概要	类/函数/变量	必须
`@details`	详细描述（可换行）	函数/类	可选
`@param[in]/[out]/[in,out]`	参数方向 + 说明	函数	每个参数都要写
`@return` / `@retval`	返回值说明	函数	有返回值就写
`@note`	调用者要注意的事项	函数/类	可选
`@warning` / `@deprecated`	警告或已废弃	函数/类	可选
`@see` / `@sa`	交叉引用	函数/类	可选
`@exception` / `@throw`	可能抛出的异常	函数	C++ 用
`@ingroup`	归属模块/组	类/函数	方便按模块索引
`@file`	文件级注释	文件头顶	必须写一次

二、文件级模板（放在 .c / .h 最顶端）

/**
 * @file  door_driver.h
 * @brief 门禁驱动对外接口
 * @author  ZhangSan <zhangsan@xxx.com>
 * @date    2025-11-18
 * @ingroup HAL
 */

三、函数级模板（无参数、无返回值版）

/**
 * @brief  关门
 * @details
 * 执行一次关门动作，内部已做防抖与超时保护；
 * 上层应用无需再延时等待。
 * @note   中断上下文不可调用
 * @retval None
 */
void door_close(void);

四、函数级模板（带参数、带返回值版）

/**
 * @brief  设置门角度
 * @param[in]  angle   目标角度，0°~90°
 * @param[out] p_err   错误码，0 表示成功
 * @return     实际写入的角度值；负值表示失败
 * @retval -1 参数越界
 * @retval -2 电机未就绪
 * @note   角度精度为 1°
 */
int  door_set_angle(uint8_t angle, int *p_err);

五、结构体 / 宏模板

/**
 * @brief  门状态枚举
 * @ingroup HAL
 */
typedef enum {
    DOOR_STATE_OPEN  = 0,  /**< 门已开到位 */
    DOOR_STATE_CLOSE = 1,  /**< 门已关到位 */
    DOOR_STATE_MOVING= 2   /**< 门正在运动 */
} door_state_e;

/**
 * @def   DOOR_MAX_RETRY
 * @brief 关门重试次数
 */
#define DOOR_MAX_RETRY  3U

六、快速生成文档

安装 Doxygen（Ubuntu 示例）
sudo apt install doxygen graphviz
在项目根目录生成默认配置文件
doxygen -g Doxyfile
修改关键选项（用编辑器打开 Doxyfile）

   PROJECT_NAME           = "DoorCtrl"
   INPUT                  = src/ inc/
   RECURSIVE              = YES
   GENERATE_HTML          = YES
   GENERATE_LATEX         = NO
   EXTRACT_ALL            = YES
---

一键出文档
doxygen Doxyfile
生成的网页在 html/index.html，可直接发布到 GitLab Pages 或内部 nginx。

七、大厂内部“隐形”要求（经验总结）

中英文统一：对外的 SDK 必须英文；内部模块可中文，但禁止混写。
@brief 不超过 80 列，禁止换行；@details 可分段空行。
参数名必须与代码完全一致，避免 “foo / 描述 /” 这种旧式注释。
任何 int 返回值，都要用 @retval 穷举所有错误码，方便自动化测试用例直接映射。
在 Git 提交钩子中增加 doxygen -s -q 检测，注释不全直接拒绝 push。

Doxygen注释风格

分享