Doxygen中如何让文件文档显示被引用的代码元素？

问题背景 #

当前环境有main.c、req.yml、dox.cfg三个文件，已做以下配置：

• main.c的foo()和bar()通过@ref req.yml引用需求文件
• req.yml添加了@file和@showrefs标签
• dox.cfg已配置FILE_PATTERNS包含yml文件、EXTENSION_MAPPING将yml映射为Python、开启REFERENCED_BY_RELATION选项

实际问题：函数文档页面正常显示引用关系，但req.yml的文档页面无任何被引用相关章节，需要在req.yml页面展示foo()和bar()对它的引用，且无需预生成代理文件。

解决方案 #

1. 修正req.yml的注释格式 #

由于已将yml映射为Python，Doxygen会按Python注释规则解析，需用#开头的单行注释包裹Doxygen标签，确保被正确识别：

# @file req.yml
# @showrefs
# 需求内容示例：
# - 功能A需求
# - 功能B需求

避免使用C风格的/** */注释，否则Doxygen无法解析YAML文件中的标签。

2. 补全配置文件关键项 #

在dox.cfg中补充/确认以下配置：

# 确保文件被纳入文档
SHOW_FILES = YES
# 开启引用关系（与REFERENCED_BY_RELATION配合）
REFERENCES_RELATION = YES
# 明确扫描当前目录
INPUT = .
# 确认扩展名映射格式正确（注意等号前后无多余空格）
EXTENSION_MAPPING = yml=Python
# 确保yml文件被扫描
FILE_PATTERNS = *.c *.yml

REFERENCES_RELATION与REFERENCED_BY_RELATION是一对配置项，前者控制“引用了谁”，后者控制“被谁引用”，需同时开启才能双向显示引用关系。

3. 明确@ref的引用类型 #

在main.c中，引用文件时添加file:前缀，明确指定引用的是文件实体，避免Doxygen解析歧义：

/**
 * @brief 实现功能A的函数
 * @ref file:req.yml
 */
void foo() {}

/**
 * @brief 实现功能B的函数
 * @ref file:req.yml
 */
void bar() {}

4. 清理缓存后重新生成 #

删除Doxygen生成的html、xml等输出目录（若存在），然后重新执行：

doxygen dox.cfg

缓存文件可能残留之前的错误配置，清理后重新生成可确保新配置生效。

完成以上步骤后，req.yml的文档页面会出现“被引用的”章节，列出foo()和bar()函数对它的引用。

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