Doxygen主页面Markdown章节错误关联至模块类的问题咨询

问题分析 #

这并非Doxygen的Bug，而是其Markdown标题解析逻辑导致的行为。当GENERATE_TREEVIEW = YES时，若主页面的Markdown三级标题未明确归属上下文，Doxygen会将其关联到最近的代码分组（如GroupA模块及A类），从而出现树形视图错误关联的情况。而\section作为Doxygen原生命令，会强制将标题归属到当前主页面，因此不会出现关联问题，但原生命令生成的标题样式尺寸确实偏大。

适配修改方案 #

1. 明确主页面上下文标识

在Introduction.txt开头添加@mainpage命令，明确当前页面为主页面，之后再使用Markdown三级标题：

@mainpage 项目主页面
### First part
这里是第一部分内容...

### Second part
这里是第二部分内容...

Doxygen会自动将这些Markdown标题归属于主页面的树形结构，不会错误关联到其他模块。

2. 配合@page命令指定页面归属

若需要更灵活的页面管理，可使用@page命令明确标记主页面，再编写Markdown标题：

@page main_page 项目主页面
### First part
内容描述...

### Second part
内容描述...

这种方式能让Doxygen清晰识别标题所属页面，避免上下文混淆。

3. 给代码模块添加明确分组

在A.h中用@defgroup命令给GroupA模块做明确分组包裹，隔离主页面标题的解析上下文：

/**
 * @defgroup GroupA 模块A
 * 模块A的描述信息
 */
/**
 * @ingroup GroupA
 * @class A
 * A类的描述信息
 */
class A {
    // 类内容
};

通过@ingroup将A类明确归属到GroupA分组，主页面的Markdown标题就不会被误关联到该分组下。

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