documentation - Doxygen 中的节名称必须是全局唯一的吗？

Question

我正在我的应用程序中编写一些模块的概述文档。我主要使用 \page、\subpage、\section 和 \subsection 标签。

\page 和 \subpage 标签使我能够为文档提供一个很好的层次结构，该结构在网页的标题中清晰可见，或者是用于在使用 QHelpGenerator 转换为 Qt 帮助时构建目录。因此，我知道页面应该有唯一的名称。

当我在页面中给我的部分命名时，例如“概述”、“简介”、“section1”、“section2”等，当我构建文档的子集时，它似乎可以正常工作。看来节名称不必是唯一的。

但是，当我构建更大的文档文件集时，某些页面不再正确创建。这可能是由于部分名称不是全局唯一造成的吗？

我尝试查找有关节名称的全局唯一性的信息，但找不到任何有关节名称的唯一性的声明。它们必须是全局唯一的吗？

编辑: 我现在注意到，如果一个文件具有 id X 和标题 A 的部分，而另一个文件具有 id X 和标题 B 的部分，则两者在生成的文档中获得相同的标题(A 或 B)。所以这似乎表明 id 应该是全局唯一的。有没有办法避免这个问题？

Answer 1

doxygen 中的节名称应是全局唯一的。这允许从文档的任何部分引用某个部分 (\ref)。

如果您只是查找节标题(其中 id 不使用/不重要)，您可以依赖 Doxygen 提供的其他机制之一来指定 header ，例如:

• 使用 HTML 标签作为标题:

  <h1>Header 1</h1>
  <h2>Header 2</h2>
  <h3>Header 3</h3>
  

• 使用 header 的 Markdown 表示形式(假设启用了 Markdown 支持):

  Header 1
  ========
  
  Header 2
  --------
  

  或

  # Header 1
  ## Header 2
  ### Header 3