如何抑制特定代码段的Doxygen「已文档化符号未声明」警告

需在启用WARN_AS_ERROR=FAIL_ON_WARNINGS的前提下，针对特定函数抑制Doxygen的「documented symbol 'x' was not declared or defined」警告。场景为外部库的函数声明通过#include嵌入类定义中，Doxygen无法解析这些声明导致误报，但需保留这些函数的文档，且不能屏蔽其他警告，@cond无法满足需求（会同时屏蔽文档）。

示例代码：

c.h 文件 #

//! blabla
namespace A
{
  //! blabla
  namespace B
  {
    //! blabla
    class C
    {
#include "lib.h" // 函数声明在此，但Doxygen无法识别
    };
  }
}

c.cpp 文件 #

using namespace A::B;

/*! 该函数声明在lib.h中，此处可补充文档，Doxygen已能自动收集该函数，符合预期。
*/
void C::foo()
{
}

方案1：让Doxygen解析外部库头文件 #

如果外部库的lib.h可被Doxygen访问，在Doxygen配置文件中添加该头文件所在目录到INCLUDE_PATH，同时确保头文件会被解析：

# Doxygen配置文件
INCLUDE_PATH += /path/to/lib/header/dir
FILE_PATTERNS += *.h # 确保头文件纳入解析范围

此方案让Doxygen识别lib.h中的函数声明，从根源消除警告，同时保留所有文档。

方案2：在cpp文件中显式关联函数与类 #

若无法让Doxygen解析lib.h，可在cpp文件的函数文档中用@fn和@class明确关联函数所属类：

using namespace A::B;

/*! 该函数声明在lib.h中，此处可补充文档，Doxygen已能自动收集该函数，符合预期。
@fn void A::B::C::foo()
@class A::B::C
*/
void C::foo()
{
}

通过@fn指定函数完整限定名、@class指定所属类，帮助Doxygen建立声明与定义的关联，从而抑制警告。

方案3：用条件编译标记局部解析头文件 #

若不想将lib.h全部内容纳入文档，仅需解析其中的函数声明，可在头文件中用条件标记包裹#include，并在配置中启用该标记：

修改c.h： #

//! blabla
namespace A
{
  //! blabla
  namespace B
  {
    //! blabla
    class C
    {
    //! @cond PARSE_LIB_DECL
    #include "lib.h"
    //! @endcond
    };
  }
}

修改Doxygen配置： #

ENABLED_SECTIONS = PARSE_LIB_DECL

此方案让Doxygen仅解析标记包裹的内容，识别函数声明的同时，不将lib.h无关内容纳入文档。

方案4：精准抑制特定警告（Doxygen 1.9.5+） #

使用Doxygen 1.9.5及以上版本时，可利用@suppress命令针对特定符号屏蔽目标警告：

using namespace A::B;

/*! 该函数声明在lib.h中，此处可补充文档，Doxygen已能自动收集该函数，符合预期。
@suppress documented symbol not declared
*/
void C::foo()
{
}

@suppress后紧跟需匹配的警告文本，可精准屏蔽该函数的特定警告，同时保留其他警告与文档。

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