如何抑制clang-tidy的-Wdocumentation空段落错误？（Doxygen场景）

为什么会触发这个错误？ #

clang-tidy的-Wdocumentation检查对Doxygen注释的完整性要求比Doxygen本身更严格。你写的@param[in] param1后面没有任何参数描述文本，clang-tidy会判定这是一个空段落——它期望每个@param命令都要跟上对该参数的用途、含义或约束的说明，哪怕是一句简单的描述。虽然Doxygen可能允许空的@param条目，但clang-tidy的这个检查规则会把它标记为问题（尤其是你开启了-Werror，会直接把警告转为错误）。

解决方法 #

1. 修复注释（推荐方案）

给每个@param补充对应的描述信息，这是最规范的做法，也能让代码文档更清晰，方便后续维护。示例：

//----------------------------------------------------------
/// 
/// @brief functionThatModifiesSomething - 用于修改指定内容的函数
/// 
/// @param[in] param1 - 第一个输入参数，负责设置目标操作的ID
/// @param[in] param2 - 第二个输入参数，负责配置修改操作的阈值
/// 
//-----------------------------------------------------------
void functionThatModifiesSomething(uint32_t param1, uint32_t param2);

2. 抑制特定警告（仅特殊场景使用）

如果确实不需要添加参数描述，可以通过以下方式禁用该警告：

• 单个函数/参数抑制：
  在@param行末尾添加NOLINT指令，或者在函数前添加NOLINTNEXTLINE：

  //----------------------------------------------------------
  /// 
  /// @brief functionThatModifiesSomething
  /// 
  /// @param[in] param1  // NOLINT(bugprone-documentation-empty-paragraph)
  /// @param[in] param2  // NOLINT(bugprone-documentation-empty-paragraph)
  /// 
  //-----------------------------------------------------------
  // NOLINTNEXTLINE(bugprone-documentation-empty-paragraph)
  void functionThatModifiesSomething(uint32_t param1, uint32_t param2);
  

• 全局配置抑制：
  在你的.clang-tidy配置文件中，移除或禁用bugprone-documentation-empty-paragraph检查：

  Checks: '*, -bugprone-documentation-empty-paragraph'
  WarningsAsErrors: '*, -bugprone-documentation-empty-paragraph'
  

内容的提问来源于stack exchange，提问作者Maggie S.