Doxygen如何将.c文件指定注释段引入/链接到.h文件生成文档

有两种Doxygen原生支持的实现方式，完全不用重复维护注释，也不需要给.c文件加大量跳过标记，维护成本很低。

方案1：用模块分组（\defgroup）实现，零额外引用 #

这是最贴合C语言开发习惯的写法，适配一个.c对应一个.h的模块化组织逻辑：

• 直接在.c文件最顶部写模块的Doxygen注释块，用\defgroup定义独立模块组，你之前写的模块概述、使用指南、注意事项、示例代码全放这个块里就行：

  /**
   * \defgroup uart_drv UART串口驱动模块
   * \brief 芯片UART外设的底层驱动
   * \details
   * 模块概述直接写这里：包括依赖的底层组件、初始化前提、线程安全等级
   *
   * ### 使用流程
   * 1. 先调用clk_enable()打开UART外设时钟
   * 2. 填充配置结构体后调用uart_init()完成初始化
   * 3. 调用uart_send()/uart_recv()做阻塞式收发
   *
   * \code{.c}
   * // 用法示例直接嵌在注释里
   * uart_cfg_t cfg = {.baudrate = 115200, .parity = UART_PARITY_NONE};
   * uart_init(UART_PORT_1, &cfg);
   * \endcode
   */
  

• 在对应的.h文件开头加\addtogroup标记，把所有对外暴露的宏、结构体、函数声明全部归到这个模块组下：

  /** \addtogroup uart_drv
   * @{
   */
  // 所有对外的类型定义、函数声明放这里，每个接口正常写功能注释即可
  void uart_init(uint8_t uart_idx, uart_cfg_t *cfg);
  int uart_send(uint8_t uart_idx, uint8_t *data, uint32_t len);
  /** @} */
  

• 调整三个Doxygen配置项，即可自动过滤.c里的冗余内容，不用手动加任何跳过标记：

  • 把对应.c和.h都加到INPUT路径列表里
  • 关闭EXTRACT_STATIC、EXTRACT_PRIVATE选项
  • 开启HIDE_UNDOC_MEMBERS选项

  配置完成后，.c里的静态函数、内部实现逻辑默认不会被提取到公开文档，只有你写在\defgroup里的模块说明、.h里的对外接口会被整合到同一个模块文档页。要是有个别内部函数写了注释不想对外展示，给注释加个\internal标记就行，默认配置下Doxygen会自动忽略这部分内容。

方案2：锚点+\copydoc定向引用 #

如果你不想用模块分组，就想把.c顶部的注释片段直接插入到.h的文件说明里，用这个方案：

• 在.c顶部的注释块里加一个唯一锚点，模块说明内容正常写即可，这个注释块不需要绑定任何函数、结构体这类代码实体：

  /**
   * \anchor uart_module_main_doc
   * 这里放你之前写的所有模块概述、使用指南内容
   */
  

• 在.h文件的文件级注释块里，直接用\copydoc引用这个锚点：

  /**
   * \file uart.h
   * \brief UART驱动对外接口头文件
   * \copydoc uart_module_main_doc
   */
  

• 要是不想让.c里的其他实现内容出现在文档里，只需要在顶部注释块结束的下一行加一行\cond INTERNAL，在.c文件最末尾加一行\endcond就行，两行标记就能跳过所有实现代码，比逐段包裹简洁得多。生成文档时Doxygen会自动把锚点对应的注释内容原封不动插到\copydoc所在位置，注释里的格式、代码块、列表都会完整保留。

完全没必要用全量包裹.c内容的方案，Doxygen本身就自带静态/私有成员的过滤开关，默认就不会提取未对外暴露的内部实现，手动加大量跳过标记纯属多余操作。

内容的提问来源于stack exchange，提问作者Kay