Merge tag 'pull-qapi-2024-07-06' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2024-07-06

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmaI6xcSHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTTbQP/AonsqGYQyOPCWae9dfDt+Wy+k2gthoB
# dn/3SRjYnA23avEv2/AGAPxgp5MHkpdhh8eqNjWq9QgqgEUh/m0nJztS/MiLMHsR
# /PENPy4V2QFf7s5XtIutLiKXgGbzwtHxrbwnCNyQZW6dAK67VBTq5hPQSxFwBVga
# FDVm+DS2JehJ7IPMVmPT5gjI2cyDYNc/rxbvcbcb5SqirfJdPFk9nMJUrQ0Qubfs
# c9D6l8Cwzbm4JfSeRThs8v9CsDZ1+OIXnpDgGAP9hr7+yYFsovLSHfiLGFxnFXiN
# gSKLBNRIzXnC9cFsKY4jXuqFoSFblRccqCtPSYb7sAp3OVwKq3kA/XNuPIAPii8S
# cm+bhVJ3lyXUW5/6qruS5tOEkpsTnXC45Uw9nvZDEVXANMn3viZ1qInxKak8Nr+p
# k0bOHGE4NzRKkAvGDaTooUOlhG4iy9M+Q4dTcwKIoXTs1Euo8uOjAL+jGwT2pan5
# fb/P1cIqMgMpwSQjwIs7LoYMk20FF44CPtuwA+m85iLbTiiuUfQ4bTnVNMOQMibq
# 3QWIrEDfxwrvwMPsv/u/hcc5d2Tb+5QP9CeVmT9woSXJqU2g4yvKKP9JBf7jUFMC
# fTpNRcHOWsIoz+AgOrUeYe67fLpqUWQii08JhPg5f4ybbEzkzZub0zOKNFLYumG0
# VT3BQlO+8LdW
# =RwDq
# -----END PGP SIGNATURE-----
# gpg: Signature made Fri 05 Jul 2024 11:58:31 PM PDT
# gpg:                using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg:                issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [full]
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>" [full]

* tag 'pull-qapi-2024-07-06' of https://repo.or.cz/qemu/armbru:
  sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments
  qapi/parser: don't parse rST markup as section headers
  qapi: add markup to note blocks
  qapi: update prose in note blocks
  qapi: convert "Note" sections to plain rST
  qapi: nail down convention that Errors sections are lists
  qapi: fix non-compliant JSON examples
  docs/qapidoc: fix nested parsing under untagged sections
  qapi/parser: fix comment parsing immediately following a doc block
  qapi/parser: preserve indentation in QAPIDoc sections
  docs/qapidoc: delint a tiny portion of the module
  docs/qapidoc: remove unused intersperse function
  qapi: linter fixups

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>

6 files changed, 40 insertions, 31 deletions

diff --git a/tests/qapi-schema/doc-empty-section.err b/tests/qapi-schema/doc-empty-section.err
index 5f03a6d..711a0d6 100644
--- a/tests/qapi-schema/doc-empty-section.err
+++ b/tests/qapi-schema/doc-empty-section.err
@@ -1 +1 @@
-doc-empty-section.json:6: text required after 'Note:'
+doc-empty-section.json:6: text required after 'Errors:'
diff --git a/tests/qapi-schema/doc-empty-section.json b/tests/qapi-schema/doc-empty-section.json
index f3384e9..f179d3e 100644
--- a/tests/qapi-schema/doc-empty-section.json
+++ b/tests/qapi-schema/doc-empty-section.json
@@ -3,6 +3,6 @@
 ##
 # @foo:
 #
-# Note:
+# Errors:
 ##
 { 'command': 'foo', 'data': {'a': 'int'} }
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index de38a38..b565895 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -55,6 +55,8 @@
 # - {braces}
 ##
 
+# Not a doc comment
+
 ##
 # @Enum:
 #
@@ -155,7 +157,7 @@
 # @cmd-feat1: a feature
 # @cmd-feat2: another feature
 #
-# Note: @arg3 is undocumented
+# .. note:: @arg3 is undocumented
 #
 # Returns: @Object
 #
@@ -163,7 +165,7 @@
 #
 # TODO: frobnicate
 #
-# Notes:
+# .. admonition:: Notes
 #
 #  - Lorem ipsum dolor sit amet
 #  - Ut enim ad minim veniam
@@ -179,6 +181,9 @@
 #  - *verbatim*
 #  - {braces}
 #
+# Note::
+#     Ceci n'est pas une note
+#
 # Since: 2.10
 ##
 { 'command': 'cmd',
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index 716a9a4..a8e9456 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -117,8 +117,8 @@ doc symbol=Base
     body=
 
     arg=base1
-description starts on a new line,
-minimally indented
+ description starts on a new line,
+ minimally indented
 doc symbol=Variant1
     body=
 A paragraph
@@ -145,8 +145,8 @@ doc symbol=Alternate
 
     arg=i
 description starts on the same line
-remainder indented the same
-@b is undocumented
+    remainder indented the same
+    @b is undocumented
     arg=b
 
     feature=alt-feat
@@ -158,36 +158,41 @@ doc symbol=cmd
     body=
 
     arg=arg1
-description starts on a new line,
-indented
+    description starts on a new line,
+    indented
     arg=arg2
 description starts on the same line
-remainder indented differently
+    remainder indented differently
     arg=arg3
 
     feature=cmd-feat1
 a feature
     feature=cmd-feat2
 another feature
-    section=Note
-@arg3 is undocumented
+    section=None
+.. note:: @arg3 is undocumented
     section=Returns
 @Object
     section=Errors
 some
     section=TODO
 frobnicate
-    section=Notes
-- Lorem ipsum dolor sit amet
-- Ut enim ad minim veniam
+    section=None
+.. admonition:: Notes
 
-Duis aute irure dolor
+ - Lorem ipsum dolor sit amet
+ - Ut enim ad minim veniam
+
+ Duis aute irure dolor
     section=Example
--> in
-<- out
+ -> in
+ <- out
     section=Examples
-- *verbatim*
-- {braces}
+ - *verbatim*
+ - {braces}
+    section=None
+Note::
+    Ceci n'est pas une note
     section=Since
 2.10
 doc symbol=cmd-boxed
@@ -198,9 +203,9 @@ a feature
     feature=cmd-feat2
 another feature
     section=Example
--> in
+ -> in
 
-<- out
+ <- out
 doc symbol=EVT_BOXED
     body=
 
diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt
index 847db70..30d457e 100644
--- a/tests/qapi-schema/doc-good.txt
+++ b/tests/qapi-schema/doc-good.txt
@@ -193,11 +193,9 @@ Features
 "cmd-feat2"
    another feature
 
+Note:
 
-Note
-~~~~
-
-"arg3" is undocumented
+  "arg3" is undocumented
 
 
 Returns
@@ -211,9 +209,7 @@ Errors
 
 some
 
-
-Notes
-~~~~~
+Notes:
 
 * Lorem ipsum dolor sit amet
 
@@ -235,6 +231,9 @@ Examples
    - *verbatim*
    - {braces}
 
+Note::
+   Ceci n'est pas une note
+
 
 Since
 ~~~~~
diff --git a/tests/qapi-schema/doc-interleaved-section.json b/tests/qapi-schema/doc-interleaved-section.json
index adb29e9..eec01ed 100644
--- a/tests/qapi-schema/doc-interleaved-section.json
+++ b/tests/qapi-schema/doc-interleaved-section.json
@@ -10,7 +10,7 @@
 #
 #           bao
 #
-# Note: a section.
+# TODO: a section.
 #
 # @foobar: catch this
 #