Qt Creator中Doxygen无法生成纯C项目文档的问题求助

我之前也碰到过类似的情况——C++项目能正常生成文档，但纯C项目输出的HTML只有空索引页。除了添加@file标签，还有不少细节需要排查，给你列几个关键方向：

• 检查Doxygen配置文件的核心选项
  打开项目根目录的Doxyfile，确认以下配置是否正确：

  • INPUT：务必指向你的C项目源码目录，比如INPUT = ./src，确保包含所有需要生成文档的.c和.h文件
  • FILE_PATTERNS：必须包含*.c和*.h，默认配置可能有，但如果被修改过要改回来：FILE_PATTERNS = *.c *.h
  • RECURSIVE：如果源码分布在子目录中，设为YES，让Doxygen递归扫描所有层级
  • PREDEFINED：如果代码里有条件编译宏（比如#ifdef MY_FEATURE），在这里预定义需要开启的宏，比如PREDEFINED = MY_FEATURE=1，避免Doxygen跳过部分代码

• 确认@file标签的正确用法
  头文件里的@file必须放在文件最顶部的Doxygen风格注释块中，格式要准确：

  /**
   * @file math_utils.h
   * @brief 基础数学工具函数的头文件
   */
  

  注意是/**开头的注释（不是普通的/*），且@file后面要跟上准确的文件名，避免Doxygen无法识别当前文件。

• 确保代码实体有符合规范的注释
  只有@file标签不足以生成有效内容，Doxygen需要函数、结构体、宏等实体的注释才会生成具体文档。比如函数注释要这样写：

  /**
   * @brief 计算两个整数的和
   * @param a 第一个加数
   * @param b 第二个加数
   * @return 两数之和的结果
   */
  int add(int a, int b);
  

  结构体、枚举同理，要用/** ... */包裹注释，并配合@brief、@param（针对结构体成员）等标签。

• 手动运行Doxygen查看日志
  别只依赖Qt Creator插件的输出，直接在项目根目录打开终端，运行doxygen Doxyfile，查看控制台的日志输出。里面会明确告诉你哪些文件被处理了，有没有找不到文档的警告（比如warning: no documentation found for function 'add' in file math_utils.c），这些警告就是定位问题的关键。

• 检查Qt Creator插件的配置
  确认插件里指定的Doxygen可执行文件路径是正确的，生成文档时有没有选择项目根目录下的自定义Doxyfile——有些插件默认会生成临时配置，可能覆盖了你手动设置的关键选项。

按这些步骤排查下来，基本能找到问题所在。我当时就是因为FILE_PATTERNS里漏了*.c，导致只扫描了头文件但没处理源文件里的函数注释，结果生成的文档是空的。

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