Ответ 1
После некоторого расследования я решил, что это ошибка, но только потому, что она немного противоречит интуиции.
Рассмотрим следующее:
The Main Section {#the_main_section}
================
Subsection One {#first}
--------------
Something highly interesting...
Документ начинается с заголовка уровня 1 (как описано здесь), поэтому Doxygen анализирует "Главная секция" как имя и название страницы. Заголовок и метка {#the_main_section}, как представляется, не учитываются после преобразования заголовка в имя страницы.
Затем обработка переходит к остальной части документа, и, когда она достигает "Подраздела 1", она считает, что нет родительского "раздела" для "подраздела" (так как "Раздел" был преобразован в имя страницы), и здесь он задыхается.
В частности, он отбрасывает подраздел (заголовок), поскольку он считает, что родительский раздел не существует. Весь другой текст остается, но рассматривается как часть "страницы" (без родительского элемента).
"Исправить" означает добавить еще один "заголовок уровня 1" после начального "заголовка уровня 1", например.
My Great Documentation (Which Becomes the Page Name)
====================================================
The First Section
=================
Q. What? I already created a level 1 heading?
A. Yup, but that was converted to a page name/title and discarded, so now
we have to create another level 1 heading for my first section. Don't
be fooled into thinking that the opening heading in this document is
still treated as an opening heading by Doxygen - it not!