doxygen markdown页面中的标题标签使标题标题消失

Question

我注意到doxygen 1.8.2有一个奇怪的问题.包含标题标签会导致标题标题从输出html中消失.

使用以下markdown文件:

Title            {#title}
=====

Section 1        {#section1}
---------
Text for section 1

我得到的输出为:

标题

第1节的文字

但是,如果我{#section1}从markdown文件中删除标签,我会得到正确的输出:

标题

第1节

第1节的文字

我在这里犯的错是什么？

编辑我在标记部分时发现了以下警告:

 warning: found subsection command outside of section context!

Answer 1

经过一番调查后,我认为这似乎是一个错误,但仅仅是因为它有点违反直觉.

考虑以下:

The Main Section {#the_main_section}
================

Subsection One {#first}
--------------

Something highly interesting...

该文件与1级头开始(如描述这里)等Doxygen的解析"一节中"作为名称和页面标题.标题{#the_main_section}转换为页面名称后,标题和标签似乎被忽略.

然后处理移动到文档的其余部分,当它到达"第一部分"时,它认为"子部分"没有父部分"(因为"部分"被转换为页面名称)并且这个是它窒息的地方.

更具体地说,它丢弃子节(标题),因为它认为没有父节"节".所有其他文本仍然存在,但被视为"页面"的一部分(没有部分父级).

"修复"是在初始"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's not!