Doxygen页面字符超限引发循环依赖错误咨询

问题明细 #

• 触发错误：label raul_1 is a subpage of itself! Please remove this cyclic dependency.
• 复现规律：页面字符数超过264000时触发该错误，低于此数值则无异常
• 页面创建相关代码片段：

|SWC               | Namespace         | File
|------------------| ------------------|------------------
|func1|std|\subpage raul_1|


\page raul_1 r1

关于字符数限制 #

这种循环依赖误报并非工具官方声明的字符数限制，大概率是解析器缓冲区溢出导致的。当单页内容长度超过阈值后，解析器的临时存储区域出现数据覆盖，错误识别了页面的关联关系，把正常的\subpage与\page绑定判定为循环依赖。

解决思路 #

• 拆分大页面：将超长内容按功能模块拆分为多个子页面，比如把raul_1拆成raul_1_part1、raul_1_part2等，再通过\subpage关联到主页面，避免单页内容触发解析异常。
• 精简内容：清理页面内冗余的注释、重复文本、空行等，压缩字符总量，降低触发缓冲区溢出的概率。
• 升级工具版本：如果使用的是Doxygen这类文档生成工具，尝试升级到最新稳定版，新版本可能修复了长页面解析的缓冲区问题。
• 调整解析参数：查找工具配置文件中与“解析缓存大小”“字符缓冲区阈值”相关的配置项，适当调大参数值，适配长页面解析需求。

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