[29/42] qapi: Add "Details:" disambiguation marker

Commit Message

John Snow Feb. 5, 2025, 11:11 p.m. UTC

This clarifies sections that are mistaken by the parser as "intro"
sections to be "details" sections instead.

Signed-off-by: John Snow <[e-mail]>
---
 qapi/machine.json      | 2 ++
 qapi/migration.json    | 4 ++++
 qapi/qom.json          | 4 ++++
 qapi/yank.json         | 2 ++
 scripts/qapi/parser.py | 8 ++++++++
 5 files changed, 20 insertions(+)

Patch

diff --git a/qapi/machine.json b/qapi/machine.json
index a6b8795b09e..3c1b397f6cc 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1301,6 +1301,8 @@ 
 # Return the amount of initially allocated and present hotpluggable
 # (if enabled) memory in bytes.
 #
+# Details:
+#
 # .. qmp-example::
 #
 #     -> { "execute": "query-memory-size-summary" }
diff --git a/qapi/migration.json b/qapi/migration.json
index 43babd1df41..9070a91e655 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -1920,6 +1920,8 @@ 
 #
 # Xen uses this command to notify replication to trigger a checkpoint.
 #
+# Details:
+#
 # .. qmp-example::
 #
 #     -> { "execute": "xen-colo-do-checkpoint" }
@@ -1993,6 +1995,8 @@ 
 #
 # Pause a migration.  Currently it only supports postcopy.
 #
+# Details:
+#
 # .. qmp-example::
 #
 #     -> { "execute": "migrate-pause" }
diff --git a/qapi/qom.json b/qapi/qom.json
index 11277d1f84c..5d285ef9239 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -729,6 +729,8 @@ 
 #
 # Properties for memory-backend-shm objects.
 #
+# Details:
+#
 # This memory backend supports only shared memory, which is the
 # default.
 #
@@ -744,6 +746,8 @@ 
 #
 # Properties for memory-backend-epc objects.
 #
+# Details:
+#
 # The @merge boolean option is false by default with epc
 #
 # The @dump boolean option is false by default with epc
diff --git a/qapi/yank.json b/qapi/yank.json
index 30f46c97c98..4d36d21e76a 100644
--- a/qapi/yank.json
+++ b/qapi/yank.json
@@ -104,6 +104,8 @@ 
 #
 # Returns: list of @YankInstance
 #
+# Details:
+#
 # .. qmp-example::
 #
 #     -> { "execute": "query-yank" }
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index c5d2b950a82..5890a13b5ba 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -544,6 +544,14 @@  def _tag_check(what: 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: