如何让Doxygen仅对部分文档化的对象显示警告

需求 #

在C++项目中集成Doxygen 1.9.1，要求：

• 已有部分文档的类/函数，若文档不完整（比如缺失参数说明），触发警告
• 完全无文档的类/函数，不触发任何警告
  以此实现无需补全全代码库文档，即可启用“警告转错误”功能。

示例代码 #

inline void hello_foo(const std::string & world)
{
  std::cout << "Hello " << world << std::endl;
}

/**
 * @brief Test incomplete documentation
 */
inline void hello_bar(const std::string & world)
{
  std::cout << "Hello " << world << std::endl;
}

• hello_foo完全无文档：不触发警告
• hello_bar有@brief但缺失参数说明：触发1条警告

尝试过的配置 #

配置1：无任何警告 #

WARNINGS               = YES
WARN_IF_UNDOCUMENTED   = NO
WARN_IF_DOC_ERROR      = YES
WARN_NO_PARAMDOC       = YES

问题：WARN_NO_PARAMDOC在WARN_IF_UNDOCUMENTED=NO时会被Doxygen忽略，无法检测到hello_bar的参数文档缺失。

配置2：产生目标警告，但额外触发无文档对象的警告 #

WARNINGS               = YES
WARN_IF_UNDOCUMENTED   = YES
WARN_IF_DOC_ERROR      = YES
WARN_NO_PARAMDOC       = YES

问题：会对hello_foo这类完全无文档的函数也触发“无文档”警告，不符合需求。

解决办法 #

由于Doxygen的设计限制：WARN_NO_PARAMDOC仅在WARN_IF_UNDOCUMENTED=YES时生效，因此需要结合外部过滤或自动标记的方式实现需求：

方法1：外部脚本过滤警告 #

保留配置2的设置，在执行Doxygen时通过脚本过滤掉“无文档”类警告，只保留文档不完整的警告。示例bash命令：

doxygen Doxyfile 2>&1 | grep -v "no documentation for"

若要启用“警告转错误”，可在过滤后检查输出内容，若存在剩余警告则退出非零：

doxygen Doxyfile 2>&1 | tee doxygen_warnings.log
grep -v "no documentation for" doxygen_warnings.log > filtered_warnings.log
if [ -s filtered_warnings.log ]; then
  echo "存在文档不完整警告"
  cat filtered_warnings.log
  exit 1
fi

方法2：自动标记无文档实体（无需手动修改代码） #

编写简单的代码预处理脚本，给完全无文档的函数/类添加@cond和@endcond标记，让Doxygen忽略这些实体的警告。例如用Python脚本扫描代码，识别无文档的函数，在其前后添加Doxygen条件注释：

# 示例脚本逻辑（需根据实际代码结构调整）
import re

with open("source.cpp", "r") as f:
    content = f.read()

# 匹配无文档的函数定义（简单示例，需适配代码风格）
pattern = re.compile(r'(inline\s+void\s+\w+\([^)]+\))', re.MULTILINE)

def add_cond(match):
    return f'/** @cond */\n{match.group(1)}\n/** @endcond */'

processed_content = pattern.sub(add_cond, content)

with open("source_processed.cpp", "w") as f:
    f.write(processed_content)

之后让Doxygen处理预处理后的代码，配合配置2即可只警告有部分文档但不完整的实体。

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