Merge tag 'pull-qapi-2025-04-08' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2025-04-08

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmf0y3ESHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTSXgP/iSQ0F/8GFqdX9+k5WJ7Sd+IzxJPkPM2
# UnjhT2viBP7pC2/Ok2NFfUnigXBCNFyLX/TNcWAK1RMfxuj9GWSJqAMxrMlTPgp0
# Oef3RdE4gQ0h/8/hA8VwdAHza9ItAdZDmpOYO1JGq1B+FVb0P8HPtwKYFhf+gMGa
# YcEuwD6DkilbPGnSEBmN7t78V7yp/pQ6SL/38O97aVyEmrVGtqAD1KiV2Va7JjVF
# GoOYivejTyqJeaY9dvPxxfWi/3HAPFN+q2giNZe+dOPuyYQ6oeryIyJM+sM1/8xG
# PTJayBnV7f8tXPvWrJVyiMC8vWropZ3ExY2/YJ2WNmhJIvrhj9pVxiCUgD18Akgf
# McvDjExVilIMNQCBnRLdrXDFWcc8Y+/GlVMB386a0X9OS+be3Am6b34MDG3UMjvy
# 6SL4fyOyfBkBNxrsJnngcMZgUf/VcwdLBGMGfpS9kjsXEQtlV9SfB3TbBnRMfh+t
# DWSLnEFh5AaYOnmGcC6+JG9sttM93+Boyq/tqi8n+38TDQswOB8q/XtSdHYd0f6L
# dEfD0kRmaOCOrWjakeRKvDJ0IvZbWl/iBmYDfSbe6cFIeMC82cR8sud7WYhZLk+D
# /Q0hMp7u7954ASxdM+P6iuPE17586edtWkk442uH/vKKkwYoPFyBN6+LSNAJEREX
# 4SHZhLuHCNNN
# =X7db
# -----END PGP SIGNATURE-----
# gpg: Signature made Tue 08 Apr 2025 03:08:33 EDT
# 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]
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* tag 'pull-qapi-2025-04-08' of https://repo.or.cz/qemu/armbru:
  qga/qapi-schema: Add a proper introduction
  storage-daemon/qapi/qapi-schema: Add a proper introduction
  qapi/qapi-schema: Address the introduction's bit rot
  qapi/qapi-schema: Update introduction for example notation
  docs/sphinx/qmp_lexer: Highlight elisions like comments, not prompts
  docs/sphinx/qmp_lexer: Generalize elision syntax
  docs/devel/qapi-code-gen: Improve the part on qmp-example directive
  docs/interop: Sanitize QMP reference manuals TOC
  docs/interop: Delete "QEMU Guest Agent Protocol Reference" TOC
  qapi/rocker: Tidy up query-rocker-of-dpa-flows example
  docs/devel/qapi-code-gen: Tidy up whitespace

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>

1 files changed, 31 insertions, 22 deletions

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index f9cfe8721f..231cc0fecf 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -763,8 +763,8 @@ Names beginning with ``x-`` used to signify "experimental".  This
 convention has been replaced by special feature "unstable".
 
 Pragmas ``command-name-exceptions`` and ``member-name-exceptions`` let
-you violate naming rules.  Use for new code is strongly discouraged. See
-`Pragma directives`_ for details.
+you violate naming rules.  Use for new code is strongly discouraged.
+See `Pragma directives`_ for details.
 
 
 Downstream extensions
@@ -1013,7 +1013,7 @@ like this::
 document the success and the error response, respectively.
 
 "Errors" sections should be formatted as an rST list, each entry
-detailing a relevant error condition. For example::
+detailing a relevant error condition.  For example::
 
  # Errors:
  #     - If @device does not exist, DeviceNotFound
@@ -1026,31 +1026,28 @@ definition.
 QMP).  In other sections, the text is formatted, and rST markup can be
 used.
 
-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
-directionality indicators (``->`` and ``<-``), and elisions (``...``).
+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
+directionality indicators (``->`` and ``<-``), and elisions.  An
+elision is commonly ``...``, but it can also be or a pair of ``...``
+with text in between.
 
 Optionally, a plaintext title may be provided by using the ``:title:``
-directive option. If the title is omitted, the example title will
+directive option.  If the title is omitted, the example title will
 default to "Example:".
 
 A simple QMP example::
 
   # .. qmp-example::
-  #    :title: Using query-block
   #
-  #    -> { "execute": "query-block" }
-  #    <- { ... }
+  #     -> { "execute": "query-name" }
+  #     <- { "return": { "name": "Fred" } }
 
-More complex or multi-step examples where exposition is needed before or
-between QMP code blocks can be created by using the ``:annotated:``
-directive option. When using this option, nested QMP code blocks must be
-entered explicitly with rST's ``::`` syntax.
-
-Highlighting in non-QMP languages can be accomplished by using the
-``.. code-block:: lang`` directive, and non-highlighted text can be
-achieved by omitting the language argument.
+More complex or multi-step examples where exposition is needed before
+or between QMP code blocks can be created by using the ``:annotated:``
+directive option.  When using this option, nested QMP code blocks must
+be entered explicitly with rST's ``::`` syntax.
 
 For example::
 
@@ -1061,11 +1058,21 @@ For example::
   #    This is a more complex example that can use
   #    ``arbitrary rST syntax`` in its exposition::
   #
-  #      -> { "execute": "query-block" }
-  #      <- { ... }
+  #     -> { "execute": "query-block" }
+  #     <- { "return": [
+  #             {
+  #               "device": "ide0-hd0",
+  #               ...
+  #             }
+  #             ... more ...
+  #          ] }
   #
   #    Above, lengthy output has been omitted for brevity.
 
+Highlighting in non-QMP languages can be accomplished by using the
+``.. code-block:: lang`` directive, and non-highlighted text can be
+achieved by omitting the language argument.
+
 
 Examples of complete definition documentation::
 
@@ -1466,7 +1473,9 @@ As an example, we'll use the following schema, which describes a
 single complex user-defined type, along with command which takes a
 list of that type as a parameter, and returns a single element of that
 type.  The user is responsible for writing the implementation of
-qmp_my_command(); everything else is produced by the generator. ::
+qmp_my_command(); everything else is produced by the generator.
+
+::
 
     $ cat example-schema.json
     { 'struct': 'UserDefOne',