如何用Doxygen同时生成单头文件C/C++库的C与C++分支文档？

刚好碰到过类似的场景，单头文件跨C/C++的Doxygen文档生成确实容易踩这个坑。分享几个实用的解决思路，你可以根据自己的需求选：

方案1：两次生成独立文档（推荐，无需修改代码） #

这是最省心的方案，完全不用改动你的库代码，只需要分两次配置Doxygen：

• 生成C++版本文档：在你的Doxyfile里添加配置项 PREDEFINED = __cplusplus，这样Doxygen会按照C环境解析代码，生成C分支的文档。
• 生成C版本文档：复制一份Doxyfile（或者临时修改原文件），移除PREDEFINED中的__cplusplus（或者添加UNDEFINED = __cplusplus），再运行Doxygen生成C分支的文档。
• 最后把两个版本的文档输出到不同目录（比如docs/c-api和docs/cpp-api），用户就能分别查看完整的C和C++接口了。

方案2：合并C/C++内容到同一文档（需修改代码） #

如果希望把两种环境的接口放在同一篇文档里展示，可以用Doxygen的条件注释标记，让它同时解析两个分支：
在代码的预处理分支周围，加上Doxygen专属的\if系列命令，示例如下：

#ifndef __cplusplus
\if !__cplusplus
/**
 * @brief C环境下的内联函数说明
 */
inline void c_only_func() {
    // C实现
}
\endif
#else
\if __cplusplus
/**
 * @brief C++环境下的内联函数说明
 */
inline void cpp_only_func() {
    // C++实现
}
\endif
#endif

这样编译时的预处理逻辑完全不受影响，但Doxygen会识别这些\if标记，把两个分支的内容都保留在文档中。读者可以通过Doxygen的宏切换功能查看对应环境的接口，或者文档会同时展示两种实现的说明。

方案3：自定义宏兼容双分支解析（进阶，需改代码+配置） #

如果想通过一次Doxygen运行生成包含双分支的文档，可以自定义一个Doxygen专属宏：

1. 在Doxyfile中开启预处理并配置：

   ENABLE_PREPROCESSING = YES
   MACRO_EXPANSION = YES
   EXPAND_ONLY_PREDEF = YES
   PREDEFINED = __cplusplus=1 _DOXYGEN_DUAL_MODE=1
   

2. 修改代码中的分支判断，让Doxygen能同时看到两边：

   // C分支：编译时只在非C++环境生效，Doxygen解析时因为_DUAL_MODE也会生效
   #if !defined(__cplusplus) || defined(_DOXYGEN_DUAL_MODE)
   /** @brief C环境接口 */
   inline void c_func() {}
   #endif
   
   // C++分支：编译时只在C++环境生效，Doxygen解析时也会生效
   #ifdef __cplusplus
   /** @brief C++环境接口 */
   inline void cpp_func() {}
   #endif
   

   这种方式能让Doxygen一次生成包含双分支的文档，但需要额外维护自定义宏，适合对文档整合度要求较高的场景。

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