如何在Doxygen中为项目根目录生成可移植的文档条目？

问题原因 #

Doxygen对根目录的路径处理逻辑特殊，直接使用\dir .会被解析为完整绝对路径，导致目录匹配失败，无法生成根目录的文档条目。

解决方法 #

方法一：修改Doxyfile配置 #

• 在Doxyfile中添加或更新以下配置项：

  STRIP_FROM_PATH = .
  

  该配置会移除文档中路径的前缀，让Doxygen正确识别相对路径表示的根目录。
• 保持根目录README.md内容不变：

  \dir .
  \brief root directory
  

• 重新执行生成命令：

  doxygen -q
  

方法二：直接使用无参数\dir命令（无需修改配置） #

• 修改根目录README.md内容为：

  \dir
  \brief root directory
  

  不带参数的\dir命令会自动关联到Doxygen当前处理的根目录。
• 重新执行doxygen -q生成文档。

验证结果 #

生成完成后，打开html/files.html，即可看到根目录条目与dir_a条目一致，包含对应的目录参考文档。

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