Question

I am writing some overview documentation of modules in my application. I mainly use the \page, \subpage, \section and \subsection tags.

The \page and \subpage tags allow me to give a nice hierarchical structure to the documentation, which is clearly visualized in the header of the web pages, or is used to build the table of contents when converted to Qt Help using QHelpGenerator. Therefore, I understand that the pages should have unique names.

When I give my sections in my pages names like ‘overview’, ‘introduction’, ‘section1’, ‘section2’ and so on, it seems to work correctly when I build a subset of my documentation. It seems that the section names don’t have to be unique.

But, when I build a larger set of documentation files, some pages are not correctly created anymore. Could this be caused by the section names that are not globally unique?

I tried to find information regarding the global-uniqueness of section names but I can’t find any statement regarding uniqueness of section names. Do they have to be globally unique?

EDIT:
I now notice that if one file has a section with id X and title A, and another file has section with id X and title B, that both get the same title in the generated documentation (A or B). So this seems to indicate that the id’s should be globally unique. Is there a way to circumvent this?

Answer 1

Section names in doxygen are intended to be globally unique. This allows a section to be referenced (\ref) from any part of the documentation.

If you’re only looking for a section heading (where the id isn’t used/important), you could rely on one of the other mechanisms for specifying a header that Doxygen provides, for example:

• Use HTML tags for headers:

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

• Use the Markdown representation of headers (assuming Markdown support is enabled):

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

  or

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