When a documentation block consists only of plaintext, there is nothing
to semantically differentiate the "intro" from the "details"
section. For the purposes of the inliner, the intro section of
documentation inlined into another documentation block will be omitted,
which may lead to unintentional omissions of details in the rendered
output.

When the delineation between "intro" and "details" is not clear because
there is no intervening description/tagged sections, the parser assumes
the entire text section is an "intro" section. This may not always be
semantically true, so this patch clarifies certain sections explicitly
as "details" sections by using an empty "Details:" marker.

Replace existing uses of "TODO:" hacks to achieve this effect with the
canonical marker.

Signed-off-by: John Snow <jsnow@redhat.com>

---

[Review note: all *.ir files are completely unchanged before and after
this patch. --js]

Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/devel/qapi-code-gen.rst | 18 ++++++++++++++++++
 qapi/machine.json            |  2 +-
 qapi/migration.json          |  4 ++--
 qapi/net.json                |  2 +-
 qapi/yank.json               |  2 +-
 scripts/qapi/parser.py       |  8 ++++++++
 6 files changed, 31 insertions(+), 5 deletions(-)

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index 06ab3547fdc..e575b54128e 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -1048,6 +1048,24 @@ definition.
 QMP).  In other sections, the text is formatted, and rST markup can be
 used.
 
+In cases where documentation consists of several paragraphs of text with
+no intervening sections to delineate them, it may become necessary to
+explicitly declare the start of the details section by using a
+"Details:" marker. For example::
+
+  ##
+  # @foobar
+  #
+  # foobar is an example definition.
+  #
+  # Details:
+  #
+  # Since there are no other sections in this documentation, the above
+  # "Details:" marker is required to mark this and subsequent paragraphs
+  # as the "Details" section. Any automatically generated documentation
+  # sections will be inserted above this point instead of below.
+  ##
+
 QMP Examples can be added by using the ``.. qmp-example::`` directive.
 In its simplest form, this can be used to contain a single QMP code
 block which accepts standard JSON syntax with additional server
diff --git a/qapi/machine.json b/qapi/machine.json
index 685e4e29b87..bc2279b2526 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1259,7 +1259,7 @@
 # Return the amount of initially allocated and present hotpluggable
 # (if enabled) memory in bytes.
 #
-# TODO: This line is a hack to separate the example from the body
+# Details:
 #
 # .. qmp-example::
 #
diff --git a/qapi/migration.json b/qapi/migration.json
index 7134d4ce47e..2142f74e3c7 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -1633,7 +1633,7 @@
 #
 # Query replication status while the vm is running.
 #
-# TODO: This line is a hack to separate the example from the body
+# Details:
 #
 # .. qmp-example::
 #
@@ -1687,7 +1687,7 @@
 #
 # Query COLO status while the vm is running.
 #
-# TODO: This line is a hack to separate the example from the body
+# Details:
 #
 # .. qmp-example::
 #
diff --git a/qapi/net.json b/qapi/net.json
index 118bd349651..c011d6dc1a9 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -1070,7 +1070,7 @@
 # switches.  This can be useful when network bonds fail-over the
 # active slave.
 #
-# TODO: This line is a hack to separate the example from the body
+# Details:
 #
 # .. qmp-example::
 #
diff --git a/qapi/yank.json b/qapi/yank.json
index f3cd5c15d60..2854a8a9d2a 100644
--- a/qapi/yank.json
+++ b/qapi/yank.json
@@ -104,7 +104,7 @@
 #
 # Query yank instances.  See `YankInstance` for more information.
 #
-# TODO: This line is a hack to separate the example from the body
+# Details:
 #
 # .. qmp-example::
 #
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 8a21e9e8b56..1d52d80e672 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -590,6 +590,14 @@ def _tag_check(this: Union['QAPIDoc.Kind', str]) -> None:
                         raise QAPIParseError(
                             self, 'feature descriptions expected')
                     have_tagged = True
+                elif line == 'Details:':
+                    _tag_check("Details")
+                    self.accept(False)
+                    line = self.get_doc_line()
+                    while line == '':
+                        self.accept(False)
+                        line = self.get_doc_line()
+                    have_tagged = True
                 elif match := self._match_at_name_colon(line):
                     # description
                     if have_tagged:
-- 
2.53.0