抑制 clang-tidy -Wdocumentation "empty paragraph" 错误

Question

我似乎找不到在哪里可以抑制这些特定错误或者为什么他们甚至首先注册。

error: empty paragraph passed to '@param' command

这是我所拥有的生成此错误的文档：

//----------------------------------------------------------
///
/// @brief functionThatModifiesSomething
///
/// @param[in] param1
/// @param[in] param2
///
//-----------------------------------------------------------
void functionThatModifiesSomething(uint32_t param1, uint32_t param2);

我之所以注意到这一点，是因为我终于打开了其中一些警告，并且我正在清理。

看到警告后，我不明白为什么当@param 不是空段落时会报错。有什么想法吗？我可以以某种方式抑制这种风格的文档警告吗？

这是完整的错误：

./path/to/somefile.hpp:570:21: error: empty paragraph passed to '@param'     command [-Werror,-Wdocumentation]
/// @param param1
    ~~~~~~~~~~~~^

我们使用 Doxygen 作为我们的文档格式。

Answer 1

@param 期望在参数名称后面有一个描述，上面没有。
所以可能的解决方法是：

/// @param[in] param1 Description #1
/// @param[in] param2 Description #2

有关 @param 文档，请参阅 http://www.doxygen.nl/manual/commands.html#cmdparam。

Clang 的文档警告通过 -Wdocumentation 启用，默认情况下禁用。有一大堆来自不同种类的文档警告，它们都是由 -Wdocumentation 启用的，但不幸的是，您不能选择退出个别警告，例如 "empty paragraph passed to @command" 警告。

抑制 clang-tidy -Wdocumentation "empty paragraph" 错误

suppress clang-tidy -Wdocumentation "empty paragraph" errors

doxygen

clang-static-analyzer

clang-tidy