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

QAPI patches patches for 2024-01-26

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmWzT/QSHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTznQQALpsbanZR+gfTDOI/kvFuoLtOdhibtxW
# /5IwAP68Hdj2unHyHRBaNQIwyAfnHlyks1ywNyv0JCAqoyLuoa/ertir3zKc/1xP
# hOer7C76jrWiL2Gg4EMxl1oWussyHLq7XtQQEmL4aLV+EnnoytUfnosUpO0Ee5Pg
# Fz1EwJi74LEfYtrZjfX/YXZrX+3PJpYywtSWlyDluER0xfjh5d3JAsrjpgcPHZKc
# fwD2W7myxnW8IRyHdIgbu6Spv0vcM39PMrIK0ZlnVKgUz+/YcMgeK0eSXd6y+FjX
# Wehd7Ik5YE8el+SvGDPEMSTCkA2CP7dEnKt9Fk1pn+N8YhPGnQxDSBQOIae5Tnbf
# rrlOrCWXqW2a5FtbG/E4SwtXZlOo1BjkSy6+xP86YwXr23DSafVaeJp4CUls+ABZ
# LX6vR0p6bxPxOwVhoYeqxv+TpdA206g0yhN7bknoIp42DG4oj81toD5Ki3fedfwC
# pPl2sxniBm4MaO57YXxFgSN0lrur5vCcPadRppGbrGEO8XaX7F+9c5OWsPh+jt1x
# /l+A7RakrTg39NR2X46D1clPj3NQHwMVNIoSJek4+nCnM7eKVhMSm9YjpQEPupt0
# Aa+5QdiKcgjYEoSljE6ZsYJIrxd0OoaSpP1BWl4P+NcjgyUGcUkQ2X3AEL8Xkm6H
# wLv5U6ob99eL
# =nXml
# -----END PGP SIGNATURE-----
# gpg: Signature made Fri 26 Jan 2024 06:23:48 GMT
# 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-2024-01-26' of https://repo.or.cz/qemu/armbru:
  qapi: Fix malformed "Since:" section tags (again)
  qapi: Indent tagged doc comment sections properly
  qapi: Fix mangled "Returns" sections in documentation
  docs/interop/bitmaps: Clean up a reference to qemu-qmp-ref
  qapi: Fix dangling references to docs/devel/qapi-code-gen.txt
  docs: Replace dangling references to docs/interop/qmp-intro.txt
  docs/devel/qapi-code-gen: Fix missing ':' in tagged section docs
  docs/devel/qapi-code-gen: Don't reserve types ending with 'Kind'

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

19 files changed, 64 insertions, 59 deletions

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index ea8228518c..76be722f4c 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -737,9 +737,8 @@ Types, commands, and events share a common namespace.  Therefore,
 generally speaking, type definitions should always use CamelCase for
 user-defined type names, while built-in types are lowercase.
 
-Type names ending with ``Kind`` or ``List`` are reserved for the
-generator, which uses them for implicit union enums and array types,
-respectively.
+Type names ending with ``List`` are reserved for the generator, which
+uses them for array types.
 
 Command names, member names within a type, and feature names should be
 all lower case with words separated by a hyphen.  However, some
@@ -990,8 +989,8 @@ this::
   # @feature: Description text
 
 A tagged section starts with one of the following words:
-"Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
-The section ends with the start of a new section.
+"Note:"/"Notes:", "Since:", "Example:"/"Examples:", "Returns:",
+"TODO:".  The section ends with the start of a new section.
 
 The second and subsequent lines of sections other than
 "Example"/"Examples" should be indented like this::
diff --git a/docs/devel/writing-monitor-commands.rst b/docs/devel/writing-monitor-commands.rst
index 2c11e71665..b6ee4fa063 100644
--- a/docs/devel/writing-monitor-commands.rst
+++ b/docs/devel/writing-monitor-commands.rst
@@ -8,8 +8,8 @@ This document doesn't discuss QMP protocol level details, nor does it dive
 into the QAPI framework implementation.
 
 For an in-depth introduction to the QAPI framework, please refer to
-docs/devel/qapi-code-gen.txt. For documentation about the QMP protocol,
-start with docs/interop/qmp-intro.txt.
+:doc:`qapi-code-gen`.  For the QMP protocol, see the
+:doc:`/interop/qmp-spec`.
 
 New commands may be implemented in QMP only.  New HMP commands should be
 implemented on top of QMP.  The typical HMP command wraps around an
diff --git a/docs/interop/bitmaps.rst b/docs/interop/bitmaps.rst
index 1de46febdc..ddf8947d54 100644
--- a/docs/interop/bitmaps.rst
+++ b/docs/interop/bitmaps.rst
@@ -166,9 +166,9 @@ Basic QMP Usage
 ---------------
 
 The primary interface to manipulating bitmap objects is via the QMP
-interface. If you are not familiar, see docs/interop/qmp-intro.txt for a broad
-overview, and `qemu-qmp-ref <qemu-qmp-ref.html>`_ for a full reference of all
-QMP commands.
+interface. If you are not familiar, see the :doc:`qmp-spec` for the
+protocol, and :doc:`qemu-qmp-ref` for a full reference of all QMP
+commands.
 
 Supported Commands
 ~~~~~~~~~~~~~~~~~~
diff --git a/include/qapi/visitor.h b/include/qapi/visitor.h
index d53a84c9ba..27b85d4700 100644
--- a/include/qapi/visitor.h
+++ b/include/qapi/visitor.h
@@ -39,7 +39,7 @@
  * limitations; see the documentation for each visitor for more
  * details on what it supports.  Also, see visitor-impl.h for the
  * callback contracts implemented by each visitor, and
- * docs/devel/qapi-code-gen.txt for more about the QAPI code
+ * docs/devel/qapi-code-gen.rst for more about the QAPI code
  * generator.
  *
  * All of the visitors are created via:
diff --git a/include/qemu/yank.h b/include/qemu/yank.h
index 1907150933..3d88af6996 100644
--- a/include/qemu/yank.h
+++ b/include/qemu/yank.h
@@ -45,7 +45,7 @@ void yank_unregister_instance(const YankInstance *instance);
  * yank_register_function: Register a yank function
  *
  * This registers a yank function. All limitations of qmp oob commands apply
- * to the yank function as well. See docs/devel/qapi-code-gen.txt under
+ * to the yank function as well. See docs/devel/qapi-code-gen.rst under
  * "An OOB-capable command handler must satisfy the following conditions".
  *
  * This function is thread-safe.
diff --git a/qapi/block-core.json b/qapi/block-core.json
index ca390c5700..3919156d49 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1361,7 +1361,7 @@
 #     target, i.e. same data and new writes are done synchronously to
 #     both.
 #
-# Since 8.2
+# Since: 8.2
 ##
 { 'struct': 'BlockJobInfoMirror',
   'data': { 'actively-synced': 'bool' } }
@@ -3080,7 +3080,7 @@
 #
 # @type: The job type
 #
-# Since 8.2
+# Since: 8.2
 ##
 { 'union': 'BlockJobChangeOptions',
   'base': { 'id': 'str', 'type': 'JobType' },
diff --git a/qapi/char.json b/qapi/char.json
index c1bab7b855..6c6ad3b10c 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -391,8 +391,8 @@
 # @rows: console height, in chars
 #
 # Note: the options are only effective when the VNC or SDL graphical
-# display backend is active. They are ignored with the GTK, Spice, VNC
-# and D-Bus display backends.
+#     display backend is active.  They are ignored with the GTK,
+#     Spice, VNC and D-Bus display backends.
 #
 # Since: 1.5
 ##
diff --git a/qapi/introspect.json b/qapi/introspect.json
index 9173e60fdd..8df1ce85ed 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -261,7 +261,7 @@
 #
 # @members: the alternate type's members, in no particular order.  The
 #     members' wire encoding is distinct, see
-#     docs/devel/qapi-code-gen.txt section Alternate types.
+#     :doc:`/devel/qapi-code-gen` section Alternate types.
 #
 # On the wire, this can be any of the members.
 #
diff --git a/qapi/machine.json b/qapi/machine.json
index b6d634b30d..aa99fa333f 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1059,10 +1059,10 @@
 #     From it we have: balloon_size = vm_ram_size - @value
 #
 # Returns:
-# - Nothing on success
-# - If the balloon driver is enabled but not functional because the
-#   KVM kernel module cannot support it, KVMMissingCap
-# - If no balloon device is present, DeviceNotActive
+#     - Nothing on success
+#     - If the balloon driver is enabled but not functional because
+#       the KVM kernel module cannot support it, KVMMissingCap
+#     - If no balloon device is present, DeviceNotActive
 #
 # Notes: This command just issues a request to the guest.  When it
 #     returns, the balloon size may not have changed.  A guest can
@@ -1097,10 +1097,10 @@
 # Return information about the balloon device.
 #
 # Returns:
-# - @BalloonInfo on success
-# - If the balloon driver is enabled but not functional because the
-#   KVM kernel module cannot support it, KVMMissingCap
-# - If no balloon device is present, DeviceNotActive
+#     - @BalloonInfo on success
+#     - If the balloon driver is enabled but not functional because
+#       the KVM kernel module cannot support it, KVMMissingCap
+#     - If no balloon device is present, DeviceNotActive
 #
 # Since: 0.14
 #
@@ -1161,10 +1161,10 @@
 # message from the guest.
 #
 # Returns:
-# - @HvBalloonInfo on success
-# - If no hv-balloon device is present, guest memory status reporting
-#   is not enabled or no guest memory status report received yet,
-#   GenericError
+#     - @HvBalloonInfo on success
+#     - If no hv-balloon device is present, guest memory status
+#       reporting is not enabled or no guest memory status report
+#       received yet, GenericError
 #
 # Since: 8.2
 #
diff --git a/qapi/migration.json b/qapi/migration.json
index eb2f883513..489b591c23 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -1597,7 +1597,7 @@
 #
 # @file: Direct the migration stream to a file.
 #
-# Since 8.2
+# Since: 8.2
 ##
 { 'enum': 'MigrationAddressType',
   'data': [ 'socket', 'exec', 'rdma', 'file' ] }
@@ -1609,7 +1609,7 @@
 #
 # @offset: The file offset where the migration stream will start
 #
-# Since 8.2
+# Since: 8.2
 ##
 { 'struct': 'FileMigrationArgs',
   'data': { 'filename': 'str',
@@ -1620,7 +1620,7 @@
 #
 # @args: command (list head) and arguments to execute.
 #
-# Since 8.2
+# Since: 8.2
 ##
 { 'struct': 'MigrationExecCommand',
   'data': {'args': [ 'str' ] } }
@@ -1630,7 +1630,7 @@
 #
 # Migration endpoint configuration.
 #
-# Since 8.2
+# Since: 8.2
 ##
 { 'union': 'MigrationAddress',
   'base': { 'transport' : 'MigrationAddressType'},
@@ -1648,7 +1648,7 @@
 #
 # @main: Main outbound migration channel.
 #
-# Since 8.1
+# Since: 8.1
 ##
 { 'enum': 'MigrationChannelType',
   'data': [ 'main' ] }
@@ -1662,7 +1662,7 @@
 #
 # @addr: Migration endpoint configuration on destination interface.
 #
-# Since 8.1
+# Since: 8.1
 ##
 { 'struct': 'MigrationChannel',
   'data': {
@@ -2126,7 +2126,7 @@
 #
 # @millisecond: value is in milliseconds
 #
-# Since 8.2
+# Since: 8.2
 #
 ##
 { 'enum': 'TimeUnit',
diff --git a/qapi/misc-target.json b/qapi/misc-target.json
index 88291453ba..9195e7d26b 100644
--- a/qapi/misc-target.json
+++ b/qapi/misc-target.json
@@ -475,7 +475,7 @@
 # @port: The port number
 #
 # Returns:
-# - Nothing on success.
+#     - Nothing on success.
 #
 # Since: 8.0
 #
diff --git a/qapi/misc.json b/qapi/misc.json
index 3622d98d01..2ca8c39874 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -344,9 +344,9 @@
 # @opaque: A free-form string that can be used to describe the fd.
 #
 # Returns:
-# - @AddfdInfo on success
-# - If file descriptor was not received, GenericError
-# - If @fdset-id is a negative value, GenericError
+#     - @AddfdInfo on success
+#     - If file descriptor was not received, GenericError
+#     - If @fdset-id is a negative value, GenericError
 #
 # Notes: The list of fd sets is shared by all monitor connections.
 #
@@ -374,8 +374,8 @@
 # @fd: The file descriptor that is to be removed.
 #
 # Returns:
-# - Nothing on success
-# - If @fdset-id or @fd is not found, GenericError
+#     - Nothing on success
+#     - If @fdset-id or @fd is not found, GenericError
 #
 # Since: 1.2
 #
diff --git a/qapi/net.json b/qapi/net.json
index 8095b68fa8..68493d6ac9 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -18,8 +18,9 @@
 #
 # @up: true to set the link status to be up
 #
-# Returns: Nothing on success If @name is not a valid network device,
-#     DeviceNotFound
+# Returns:
+#     - Nothing on success
+#     - If @name is not a valid network device, DeviceNotFound
 #
 # Since: 0.14
 #
@@ -44,8 +45,9 @@
 #
 # Since: 0.14
 #
-# Returns: Nothing on success If @type is not a valid network backend,
-#     DeviceNotFound
+# Returns:
+#     - Nothing on success
+#     - If @type is not a valid network backend, DeviceNotFound
 #
 # Example:
 #
@@ -64,8 +66,9 @@
 #
 # @id: the name of the network backend to remove
 #
-# Returns: Nothing on success If @id is not a valid network backend,
-#     DeviceNotFound
+# Returns:
+#     - Nothing on success
+#     - If @id is not a valid network backend, DeviceNotFound
 #
 # Since: 0.14
 #
diff --git a/qapi/qapi-util.c b/qapi/qapi-util.c
index 63596e11c5..65a7d18437 100644
--- a/qapi/qapi-util.c
+++ b/qapi/qapi-util.c
@@ -112,7 +112,7 @@ bool qapi_bool_parse(const char *name, const char *value, bool *obj, Error **err
  * It may be prefixed by __RFQDN_ (downstream extension), where RFQDN
  * may contain only letters, digits, hyphen and period.
  * The special exception for enumeration names is not implemented.
- * See docs/devel/qapi-code-gen.txt for more on QAPI naming rules.
+ * See docs/devel/qapi-code-gen.rst for more on QAPI naming rules.
  * Keep this consistent with scripts/qapi-gen.py!
  * If @complete, the parse fails unless it consumes @str completely.
  * Return its length on success, -1 on failure.
diff --git a/qapi/qdev.json b/qapi/qdev.json
index 6bc5a733b8..25bac5e611 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -89,8 +89,9 @@
 #
 # @id: the device's ID or QOM path
 #
-# Returns: Nothing on success If @id is not a valid device,
-#     DeviceNotFound
+# Returns:
+#     - Nothing on success
+#     - If @id is not a valid device, DeviceNotFound
 #
 # Notes: When this command completes, the device may not be removed
 #     from the guest.  Hot removal is an operation that requires guest
diff --git a/qapi/qom.json b/qapi/qom.json
index 95516ba325..84af23fe24 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -1056,8 +1056,9 @@
 #
 # Create a QOM object.
 #
-# Returns: Nothing on success Error if @qom-type is not a valid class
-#     name
+# Returns:
+#     - Nothing on success
+#     - Error if @qom-type is not a valid class name
 #
 # Since: 2.0
 #
@@ -1078,8 +1079,9 @@
 #
 # @id: the name of the QOM object to remove
 #
-# Returns: Nothing on success Error if @id is not a valid id for a QOM
-#     object
+# Returns:
+#     - Nothing on success
+#     - Error if @id is not a valid id for a QOM object
 #
 # Since: 2.0
 #
diff --git a/qapi/yank.json b/qapi/yank.json
index 87ec7cab96..60eda20816 100644
--- a/qapi/yank.json
+++ b/qapi/yank.json
@@ -77,8 +77,8 @@
 # Takes a list of @YankInstance as argument.
 #
 # Returns:
-# - Nothing on success
-# - @DeviceNotFound error, if any of the YankInstances doesn't exist
+#     - Nothing on success
+#     - @DeviceNotFound error, if any of the YankInstances doesn't exist
 #
 # Example:
 #
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index bf31018aef..48cd55a38c 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -71,7 +71,7 @@ class QAPISchemaParser:
     Parse QAPI schema source.
 
     Parse a JSON-esque schema file and process directives.  See
-    qapi-code-gen.txt section "Schema Syntax" for the exact syntax.
+    qapi-code-gen.rst section "Schema Syntax" for the exact syntax.
     Grammatical validation is handled later by `expr.check_exprs()`.
 
     :param fname: Source file name.
diff --git a/util/yank.c b/util/yank.c
index abf47c346d..eaac50539c 100644
--- a/util/yank.c
+++ b/util/yank.c
@@ -35,7 +35,7 @@ typedef struct YankInstanceEntry YankInstanceEntry;
 /*
  * This lock protects the yank_instance_list below. Because it's taken by
  * OOB-capable commands, it must be "fast", i.e. it may only be held for a
- * bounded, short time. See docs/devel/qapi-code-gen.txt for additional
+ * bounded, short time. See docs/devel/qapi-code-gen.rst for additional
  * information.
  */
 static QemuMutex yank_lock;