如何配置Doxygen避免XML输出中转义尖括号？

问题描述 #

我在头文件中使用Doxygen的\verbatim块，生成XML输出时，块内的>会被转义成>。目前我通过Breathe调用Doxygen，想要在块中编写带自定义文本的ReST交叉引用（如:ref:自定义文本<标签>``），但转义后的尖括号会导致ReST处理失败。我试过Doxygen 1.8.17和1.9.6版本，也尝试过配置别名、CDATA等方法，均无效，请问该如何配置Doxygen阻止这个转义？

解决方案 #

1. 用\code块替代\verbatim #

Doxygen的\code块对特殊字符的转义逻辑更宽松，不会自动转义>。只需将原有的\verbatim/\endverbatim替换为\code/\endcode即可：

/*!
 * \brief 示例函数说明
 * \code
 * :ref:`自定义文本<标签>`
 * \endcode
 */

生成XML时，>会保持原格式，Breathe处理后ReST能正确识别交叉引用语法。

2. 调整Doxygen配置文件 #

在Doxyfile中添加或修改以下配置项：

XML_PROGRAMLISTING = NO

该配置会关闭代码块的XML特殊字符转义，但注意可能影响其他代码块的XML输出格式，建议测试后再投入使用。

3. 用\htmlonly包裹目标内容 #

如果需要保留\verbatim块，可以用\htmlonly和\endhtmlonly包裹ReST交叉引用代码，Doxygen会跳过对这段内容的转义处理：

/*!
 * \brief 示例函数说明
 * \verbatim
 * \htmlonly
 * :ref:`自定义文本<标签>`
 * \endhtmlonly
 * \endverbatim
 */

需要注意的是，部分Doxygen版本中，Breathe对\htmlonly块的解析可能需要额外适配，建议结合实际版本测试。

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