抑制特定的 Doxygen 警告

Question

似乎其他人以前也问过这个问题。只是想检查一下是否找到了答案。

我经常遇到以下情况：在记录各种函数时，有时我会遇到希望记录一些函数参数但不记录其他参数的情况。例如，

/** 
 * This is the brief description for the function.
 * And here is the detailed description.
 * @param foo This parameter is not self-explanatory and needs a blurb
 */
void some_function(void *foo, int self_explanatory) {
    // function does stuff
}

在 Doxygen 文档中添加 self_explanatory 参数只会增加混乱，所以我宁愿不使用它。但是，Doxygen 警告该参数未记录在案。我正在使用 Eclox，但有一堆我不关心的警告突出显示很烦人。

现在，我的 doxyfile 设置了以下选项：

EXTRACT_ALL          = YES
WARNINGS             = YES
WARN_IF_UNDOCUMENTED = NO
WARN_IF_DOC_ERROR    = YES
WARN_NO_PARAM_DOC    = NO

仍然会生成警告。

一种选择是在有问题的代码周围添加@cond 和@endcond，但是没有为我的函数生成任何文档。我想要文档，而不是警告。

我正在寻找的是...

/** @nowarn
 * This is the brief description for the function.
 * And here is the detailed description.
 * @param foo This parameter is not self-explanatory and needs a blurb
 * @endnowarn
 */
void some_function(void *foo, int self_explanatory) {
    // function does stuff
}

...以便在封闭的代码块中不会生成警告。

我发现的其他 SO 问题：
Suppressing Doxygen warnings
Suppress doxygen warning for undocumented member function, but leave synopsis in place
Is it possible to choose which Doxygen warning to show?

Answer 1

这种情况下我通常会写

@param self_explonatory

（只声明参数而没有任何描述）。这通常是明智的，因为参数然后显示在参数表中。

（不过，我真的很想有一些选项来暂时禁用其他情况下的警告......）

Answer 2

只需记录 self_explanatory 参数，或者记住警告就是：警告。所有 Doxygen 都在告诉您，您可能忽略了一些事情。

您可以接受警告，也可以忽略它。如果您真的想抑制该警告，您可能需要查看您链接的第一个线程。具体来说，https://stackoverflow.com/a/25137529/3121160。