在 Doxygen 中，@subpage 和 @section 是用于组织文档内容的标签，但它们的用途、作用范围和呈现方式有显著区别。以下是两者的详细对比和说明：

1. 定义与用途

• @section：
• 用于在当前页面或文档块中定义一个章节（section）。
• 通常用于对内容进行分段，组织页面内的子主题或小节。
• 章节是页面内部的结构化部分，适合描述功能的细节、步骤或其他细分内容。
• 不会创建单独的页面，而是作为当前页面的一部分渲染。
• @subpage：
• 用于在当前页面中引用一个子页面，通常链接到由 @page 标签定义的独立页面。
• 旨在构建文档的层次结构，将相关页面组织为父子关系。
• 子页面是独立的文档页面，适合描述较大的主题或模块。

2. 语法

• @section：
• @section section_id 章节标题
  章节内容...
• section_id 是唯一标识符，用于引用。
• 后接标题和内容，内容直接嵌入当前页面。
• @subpage：
• @subpage page_id
• page_id 是由 @page 定义的页面的标识符。
• 仅引用子页面，不直接包含子页面的内容，而是生成链接或层次结构。

3. 使用场景

• @section：
• 适合在单个页面内划分内容，例如描述类的功能、安装步骤或 FAQ。
• 示例：在用户指南页面中，将“安装”和“使用方法”分为两个章节。
• @page userguide 用户指南
  # 用户指南
  
  @section install 安装
  运行 `make install` 安装依赖。
  
  @section usage 使用方法
  创建 `Calculator` 实例并调用方法。
• @subpage：
• 适合将文档组织为多级结构，例如将主页面和子模块页面关联起来。
• 示例：在主页面中引用“计算器模块”和“高级功能”两个子页面。
• @page main 主文档
  # 项目文档
  
  本项目提供计算器功能，详情见子页面：
  - @subpage calc
  - @subpage advanced
  
  @page calc 计算器模块
  # 计算器模块
  提供加法和除法运算。
  
  @page advanced 高级功能
  # 高级功能
  介绍复杂运算。

4. 文档输出效果

• @section：
• 在生成的 HTML 文档中，@section 渲染为页面内的标题（通常是 <h2> 或 <h3>，具体取决于层级）。
• 所有章节内容直接显示在当前页面，页面导航可能包含章节锚点链接。
• 例如，上述 @section install 会生成一个“安装”标题，后接相关内容。
• @subpage：
• 在生成的 HTML 文档中，@subpage 通常渲染为指向子页面的链接，或在导航树中显示为子节点。
• 子页面内容不会直接嵌入父页面，而是作为独立的页面存在。
• 例如，上述 @subpage calc 会生成一个指向“计算器模块”页面的链接。

5. 层级与嵌套

• @section：
• 支持嵌套，使用 @subsection 定义子章节。
• 嵌套层级有限（通常为 @section 和 @subsection 两级）。
• 示例：
• @section main_section 主要章节
  主要内容...
  
  @subsection sub_section 子章节
  子内容...
• @subpage：
• 支持多级页面层次结构，通过多次使用 @subpage 构建树状文档。
• 子页面可以进一步包含自己的 @subpage，形成深层嵌套。
• 示例：
• @page main 主页面
  - @subpage child
  
  @page child 子页面
  - @subpage grandchild
  
  @page grandchild 孙页面
  孙页面内容...

6. 典型用例对比

7. 结合使用的示例

以下是一个结合 @section 和 @subpage 的 Markdown 文件示例，展示如何组织文档：

 @page main 项目文档
 # 项目文档
 
 本项目提供计算器功能，分为以下部分：
 
 @section overview 概述
 这是一个简单的计算器，支持加法和除法。
 
 @section modules 模块
 详细模块说明见以下子页面：
 - @subpage calc
 - @subpage advanced
 
 @page calc 计算器模块
 # 计算器模块
 
 @section calc_intro 简介
 提供基本数学运算。
 
 @section calc_usage 使用方法
 创建 `Calculator` 实例并调用方法。
 
 @page advanced 高级功能
 # 高级功能
 
 @section adv_intro 简介
 介绍复杂运算支持。

输出效果：

• “项目文档”页面包含：
• “概述”章节（@section overview）。
• “模块”章节（@section modules），其中列出指向“计算器模块”和“高级功能”的链接（@subpage）。
• “计算器模块”页面包含：
• “简介”章节（@section calc_intro）。
• “使用方法”章节（@section calc_usage）。
• “高级功能”页面类似，独立呈现其内容。

8. 注意事项

• @section：
• 确保 section_id 唯一，避免冲突。
• 不要在 @section 中嵌套过多层级（建议最多两级：@section 和 @subsection）。
• @subpage：
• 引用的 page_id 必须对应有效的 @page 标签，否则 Doxygen 会忽略或报错。
• 子页面不会自动包含父页面内容，需手动用 @ref 或 @subpage 建立链接。
• 配置：
• 确保 Doxyfile 中的 INPUT 包含 .md 文件。
• 启用 MARKDOWN_SUPPORT = YES 以支持 Markdown 语法。
• 导航：
• @subpage 更适合生成导航树，适合大型项目。
• @section 更适合页面内快速导航，适合内容较集中的页面。

总结

• 使用 @section 当你需要在页面内组织内容，分成清晰的章节。
• 使用 @subpage 当你需要创建独立的子页面，并构建文档的层次结构。
• 两者可以结合使用，@section 管理页面内结构，@subpage 管理页面间关系。