C项目文档注释嵌入代码片段的最佳实践：兼容doxygen与clang-format

针对clang-format会破坏Doxygen @code 块内代码结构，同时又想保留其他注释格式化的需求，以下是几种实用的最佳实践：

1. 用clang-format区域排除标记精准跳过代码块 #

直接在@code前添加// clang-format off，@endcode后添加// clang-format on，仅跳过代码片段的格式化，其余注释内容仍会被clang-format正常处理：

/**
 * 这是一段会被clang-format自动格式化的普通注释，用于说明函数/变量功能
 * // clang-format off
 * @code
 * char *a_very_very_very_long = "which makes it need to enter another line to fix";
 * if (foo > 1) {
 *     return;
 * }
 * @endcode
 * // clang-format on
 */
int foo = 0;

注意：这些标记要放在注释内部，clang-format默认支持该规则，无需额外配置。

2. 替换@code为@verbatim块 #

Doxygen的@verbatim块会强制原样保留内容，部分clang-format版本对@verbatim块的格式化行为更克制，不会打乱代码结构：

/**
 * 普通注释内容，正常被clang-format格式化
 * @verbatim
 * char *a_very_very_very_long = "which makes it need to enter another line to fix";
 * if (foo > 1) {
 *     return;
 * }
 * @endverbatim
 */
int foo = 0;

如果遇到clang-format仍会处理的情况，可以结合第一种方法的排除标记，双重保障。

3. 自定义clang-format配置规则 #

在项目的.clang-format文件中添加CommentPragmas配置，让clang-format识别并跳过@code相关块：

CommentPragmas: '@(code|endcode)'

该配置会让clang-format忽略包含@code或@endcode的注释行及其关联内容，不过不同clang-format版本的匹配逻辑可能有差异，建议测试后使用。

4. 外部工具预处理注释（适合批量/CI场景） #

用脚本（如sed、Python）在clang-format执行前，将@code块替换为临时占位符，格式化完成后再恢复原内容。这种方法适合批量处理代码或CI流水线，日常开发稍显繁琐。

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