首次使用Doxygen生成C项目文档仅成功部分内容的问题排查

1. CMake配置是核心问题 #

你的CMakeLists.txt里的configure_file路径完全搞反了：

configure_file(${CMAKE_CURRENT_BINARY_DIR}/Doxyfile ${DOXYGEN_CONFIG} @ONLY)

这行是从构建目录查找Doxyfile来生成，但正常逻辑应该是从源码目录的Doxyfile模板生成到构建目录。如果你的Doxyfile放在源码根目录，得改成：

configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile ${DOXYGEN_CONFIG} @ONLY)

更关键的是：默认Doxyfile的INPUT参数是空的，你得明确告诉Doxygen要扫描哪些文件。可以选两种方式：

• 直接在Doxyfile里写死：INPUT = ./（扫描当前目录所有文件）
• 通过CMake传参更灵活：
  1. 把源码里的Doxyfile改名为Doxyfile.in，在里面添加一行：INPUT = @DOXYGEN_INPUT_FILES@
  2. 在CMakeLists.txt里添加：

     set(DOXYGEN_INPUT_FILES ${SOURCES} ${HEADERS})
     

这样CMake会把你定义的所有源文件和头文件传递给Doxyfile，保证Doxygen能扫到目标文件。

另外，你的add_custom_target里的工作目录设置为构建目录，配合Doxyfile里的OUTPUT_DIRECTORY = output是没问题的，但要确保路径对应一致。

2. Doxyfile必须调整这几个关键参数 #

默认配置里的几个开关没开，是导致文档生成不全的重要原因：

• EXTRACT_ALL = YES：强制提取所有代码实体（哪怕注释不标准），先让所有内容显示出来，再逐步优化注释。
• JAVADOC_AUTOBRIEF = YES：自动把Javadoc风格注释的第一行当成简要说明，不用手动加@brief，适配你的注释习惯。
• FILE_PATTERNS = *.c *.h：确保Doxygen识别C源文件和头文件（默认是开启的，但万一被修改过要检查）。

3. 注释格式不规范，Doxygen无法识别 #

你的注释写法不符合Doxygen的解析规则，导致参数、返回值无法正常显示：

• 结构体注释：不能照搬函数注释的写法，结构体成员需要用@field标签，比如：

  /**
   * 信号信息结构体
   * @field signal_num 信号编号
   * @field signal_desc 信号描述
   */
  typedef struct structOfSignals {
      int signal_num;
      char* signal_desc;
  } structOfSignals;
  

• 函数注释：别用Parameters:这种纯文本标题，要改用Doxygen的@param和@return标签，比如sigHandler的注释要改成：

  /**
   * 处理接收到的信号
   * @param sig 接收到的信号编号
   * @return 无返回值
   */
  void sigHandler(int sig) { ... }
  

• 文件注释：//@file main.c这种单行注释识别率低，改成/** @file main.c */或者/// @file main.c更稳妥。

4. 验证步骤 #

1. 先修复CMake的configure_file和Doxyfile的INPUT配置，确保Doxygen能扫描到所有目标文件。
2. 打开EXTRACT_ALL = YES，生成文档，检查所有函数、结构体是否都能显示。
3. 将注释改成标准的Doxygen标签，验证参数、返回值是否能正常显示。
4. 最后可以关掉EXTRACT_ALL，只保留需要生成文档的实体注释，让文档更整洁。

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