如何配置clang-format跳过@code与@endcode间的代码格式化

核心结论 #

不存在适配所有clang-format版本的零改造原生配置，可通过两种可落地的方式，实现@code与@endcode之间的内容不被格式化的需求。

方案1：全版本兼容的官方跳过语法 #

• 直接在@code代码段的上下，插入clang-format的标准格式化开关注释，注释本身属于Doxygen块的普通内容，不会干扰最终生成的文档效果。
  示例写法：

/**
 * 示例
 * @code
 * // clang-format off
 * int main()
 * {
 *  return 0;
 * }
 * // clang-format on
 * @endcode
 */

• 特点：不受clang-format版本限制，是官方指定的强制跳过格式化机制，插入后无论后续配置如何调整，被两行开关包裹的内容都不会被自动重排。

方案2：高版本自定义关键字绑定（无额外注释开销） #

• 针对clang-format 14及以上版本，可直接在.clang-format配置文件中，将@code、@endcode映射为格式化开关的触发关键字，完全不需要手动插入额外的开关注释行。
  配置写法：

---
FormatOff: ["@code"]
FormatOn: ["@endcode"]

• 特点：配置生效后，clang-format的扫描逻辑会将注释内的@code等价于跳过格式化触发点，@endcode等价于恢复格式化触发点，完全贴合原有@code块的格式边界，不需要额外维护手动插入的开关行。

常见误区提醒：CommentPragmas这类注释类配置仅能控制注释内容本身的排版规则，无法实现整块内容跳过格式化的效果，不要混淆配置的能力边界。

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