如何阻止clang-format移除Doxygen注释中的Markdown换行符

AI 小北

2026-7-7

解决Doxygen Markdown注释换行与clang-format冲突的方案

以下是针对clang-format 14（Google风格）的可行解决方案：

禁用注释重排保留行尾空格
在你的.clang-format配置里加上这一行：
```
ReflowComments: false
```
这个配置会让clang-format完全保留注释的原始格式，包括行尾空格，完美适配Markdown的换行需求。但副作用是clang-format不会再自动调整长注释的换行长度，超过字符限制的注释需要手动拆分，可能和Google风格的注释长度规范略有冲突。
用Doxygen段落标记替代Markdown换行
放弃依赖行尾空格，改用Doxygen原生的段落标记或空行来实现换行效果：
```
/// @par 功能概述
/// 这是第一行描述文本
/// 这是第二行描述文本，会被Doxygen识别为同一段落的换行
///
/// 空行分隔的内容会自动成为新段落
```
这种写法完全兼容clang-format，不会被格式化破坏，Doxygen的渲染效果和Markdown换行一致。唯一的小问题是需要习惯Doxygen的标记语法，和纯Markdown写法有一点差异。
用Markdown反斜杠硬换行
虽然不如纯行尾空格自然，但可以在换行前加反斜杠，clang-format不会移除反斜杠，Doxygen也能识别为换行：
```
/// 第一行描述内容\
/// 第二行描述内容
```
这种方式比HTML的<br>更贴近Markdown风格，也不需要额外的clang-format配置。