如何让Doxygen生成仅含易处理未归档项的独立页面？

一、生成未归档项独立页面 #

Doxygen没有原生功能直接生成未归档项专属页面，但可以通过两种方式实现：

• 解析警告日志生成文档：Doxygen运行时会输出warning: <项名> is not documented格式的警告，用脚本（Python/Bash均可）提取所有未归档项，将其整理为.dox文件作为Doxygen的输入，即可生成独立列表页面。
• 自定义HTML模板：开启EXTRACT_ALL=YES后，Doxygen会将所有代码项纳入文档，未归档项仅显示基本信息。可以修改Doxygen的HTML模板，添加一个专门页面，通过CSS选择器或模板变量筛选出无文档的成员。

二、筛选"低挂果实"未归档项 #

Doxygen本身不支持内置的依赖分析筛选，但可以借助它生成的调用关系数据实现：

1. 准备数据 #

在现有Doxyfile中添加配置：

GENERATE_XML = YES

开启后，Doxygen会在输出目录的xml子文件夹中生成包含完整调用关系、文档状态的结构化数据，方便后续解析。

2. 筛选逻辑 #

编写脚本完成以下步骤：

• 从Doxygen警告日志中提取所有未归档项；
• 对每个未归档项分类处理：
  • 结构体、常量、枚举等非函数类型，直接归为"低挂果实"；
  • 函数类型，检查其调用的所有外部项：若所有被调用项要么已归档，要么是系统库函数（无文档但无需自行归档），则归为"低挂果实"；
• 将筛选结果整理为Doxygen可识别的.dox文件，用\defgroup标记为独立分组。

3. 简化脚本示例（Bash） #

# 提取未归档项列表
grep "warning:.*is not documented" doxygen.log | awk '{print $3}' > undocumented_items.txt

# 筛选低挂果实
touch low_hanging.txt
for item in $(cat undocumented_items.txt); do
  # 处理非函数类型
  if grep -q "<memberdef kind=\"variable\"\|kind=\"struct\"\|kind=\"enum\"" doxygen/xml/$item.xml 2>/dev/null; then
    echo "$item" >> low_hanging.txt
    continue
  fi
  # 检查函数调用的所有引用是否已归档
  references=$(grep "<reference refid=" doxygen/xml/$item.xml 2>/dev/null | awk -F'"' '{print $2}')
  all_documented=true
  for ref in $references; do
    if ! grep -q "<briefdescription>[^<]*</briefdescription>" doxygen/xml/$ref.xml 2>/dev/null; then
      all_documented=false
      break
    fi
  done
  if $all_documented; then
    echo "$item" >> low_hanging.txt
  fi
done

# 生成Doxygen文档文件
cat > low_hanging.dox << EOF
\defgroup low_hanging_fruits 低挂果实未归档项
\brief 无需依赖未归档代码、易于补充文档的项列表

EOF
while read -r item; do
  echo "\ref $item" >> low_hanging.dox
done < low_hanging.txt

三、配置与使用 #

1. 将生成的low_hanging.dox添加到Doxyfile的INPUT中；
2. 重新运行Doxygen，即可在文档中看到"低挂果实未归档项"的独立分组页面。

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