多目标C语言CMake项目中Doxygen的配置问题

一、先排查Doxygen核心配置 #

你遇到的C文件未被解析的问题，大概率是Doxygen默认规则导致的，先调整Doxyfile的关键参数：

• INPUT：必须明确包含项目的头文件和C源文件目录/路径，不能只放头文件
• FILE_PATTERNS：添加*.c，比如设置为FILE_PATTERNS = *.h *.c，确保Doxygen识别C源文件
• EXTRACT_ALL = YES：强制提取所有符号（适合初期调试，后续可改回NO只保留带注释的内容）
• EXTRACT_STATIC = YES：如果C文件里有静态函数、静态变量需要生成文档，必须开启这个选项（Doxygen默认忽略静态符号）

二、CMake配置关联多目标与Doxygen #

不用为每个目标单独写重复规则，写一个通用函数批量处理更高效：

1. CMake核心配置代码 #

# 查找系统中的Doxygen
find_package(Doxygen REQUIRED)

# 定义生成单个目标文档的通用函数
function(add_target_doxygen TARGET_NAME)
    # 用模板生成目标专属的Doxyfile
    set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
    set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile_${TARGET_NAME})

    # 获取目标的源文件和头文件路径
    get_target_property(TARGET_SOURCES ${TARGET_NAME} SOURCES)
    get_target_property(TARGET_INCLUDE_DIRS ${TARGET_NAME} INCLUDE_DIRECTORIES)

    # 替换Doxyfile模板中的变量
    configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)

    # 创建目标专属的文档生成任务
    add_custom_target(doc_${TARGET_NAME}
        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
        COMMENT "生成${TARGET_NAME}的Doxygen文档"
        VERBATIM
    )

    # 可选：让文档任务依赖原目标，确保代码编译后再生成文档
    add_dependencies(doc_${TARGET_NAME} ${TARGET_NAME})
endfunction()

# 定义你的项目目标示例
add_library(my_lib src/lib.c include/lib.h)
target_include_directories(my_lib PUBLIC include)

add_executable(my_exe src/main.c)
target_link_libraries(my_exe PRIVATE my_lib)

# 为每个目标调用文档生成函数
add_target_doxygen(my_lib)
add_target_doxygen(my_exe)

2. Doxyfile.in模板关键内容 #

在项目根目录创建Doxyfile.in模板，预留CMake可替换的变量：

PROJECT_NAME           = "@TARGET_NAME@"
INPUT                  = "@TARGET_SOURCES@" "@TARGET_INCLUDE_DIRS@"
FILE_PATTERNS          = *.h *.c
EXTRACT_ALL            = YES
EXTRACT_STATIC         = YES
OUTPUT_DIRECTORY       = "${CMAKE_CURRENT_BINARY_DIR}/doc_@TARGET_NAME@"

三、常见误区修正 #

• 不要只依赖头文件：C语言的静态函数、内部逻辑实现多在.c文件中，必须将其纳入Doxygen输入范围
• 注释格式要规范：///是Doxygen支持的单行注释格式，但要确保注释紧跟被注释的符号（比如函数定义前不能有空行）
• 检查排除规则：确认Doxyfile中的EXCLUDE_PATTERNS没有误排除*.c文件或你的源文件目录

四、思路验证 #

为每个目标单独生成文档是完全可行的，能让每个模块的文档结构更清晰独立。如果需要汇总所有目标的文档，也可以将所有目标的源文件和头文件统一传入同一个Doxygen配置，生成一份全局文档。

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