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

QAPI patches patches for 2024-03-04

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmXlaSISHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTdZ8P/iMgqLoAFkCCjwfkUc/rqZUezK52Ynr7
# LYwOPI/xcYD7EnVogdRgFgjWFNoivQLP5yKsU/eRTk29pwdDzTscFm/0ztTQX/Gb
# ypWV+GBcu5J8mKbp1KF5w68aDD8Bat4WRfEgDQ1DV7v6CoMiUzTiF3CGXkYzqK5Y
# kYNq97vdEkBFvFdOl/7scs/XXN2jG27egDhMp68RTxnPHlXZiAO9/2Bul3uVe3x0
# fzQ2ViYv0qLnjE/PwENDqqE3Thv3Sxp5iEeQQ6GWi07EVh07UtHpOM3RYyrTU0Sb
# VrTApSrg0oxlkOuR0CBd9Fi+timtbokBL0DWyUpXNTfIEZfLtA9H+8riUg3EOcDp
# r7a4SI/27VdPxX6Kc6zA3bi+/j1o7CLTW2LGEwuZs52nmixoo1HTWPIFdyh13g/V
# QjNbun0fViHb0FVLiyDlXF/7Y+EWUWIyqwwGqbvve1DyUHQmo3CUQAKGOpkeKSBe
# 4eGciVDgpBoKhtw9Kv6LCDj2cwZKC8DxBMibf7GHkOnAsX2mnyuHcey7HvYNCoF+
# yYz7oIEXdlL2eWqg7CfBZK7lniCDln50RI4Ll1v+J4r1v1kRZGMLesTYXCdNc4ku
# yb4kpU4t22/RODffLE7K+fc3Onwze3fcfxlZMN66F+wFtk4KdPR2aQBE66bB8J99
# vuSKlTbT4cGL
# =s9AR
# -----END PGP SIGNATURE-----
# gpg: Signature made Mon 04 Mar 2024 06:24:34 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-03-04' of https://repo.or.cz/qemu/armbru:
  migration: simplify exec migration functions
  qapi: New strv_from_str_list()
  qapi: New QAPI_LIST_LENGTH()
  docs/devel/writing-monitor-commands: Minor improvements
  docs/devel/writing-monitor-commands: Repair a decade of rot
  qapi: Reject "Returns" section when command doesn't return anything
  qga/qapi-schema: Fix guest-set-memory-blocks documentation
  qga/qapi-schema: Tweak documentation of fsfreeze commands
  qga/qapi-schema: Clean up "Returns" sections
  qga/qapi-schema: Delete useless "Returns" sections
  qga/qapi-schema: Move error documentation to new "Errors" sections
  qapi/yank: Tweak @yank's error description for consistency
  qapi: Clean up "Returns" sections
  qapi: Delete useless "Returns" sections
  qapi: Move error documentation to new "Errors" sections
  qapi: New documentation section tag "Errors"
  qapi: Slightly clearer error message for invalid "Returns" section
  qapi: Memorize since & returns sections

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

19 files changed, 113 insertions, 186 deletions

diff --git a/qapi/block-core.json b/qapi/block-core.json
index 22b8634..1874f88 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1456,8 +1456,7 @@
 #
 # @size: new image size in bytes
 #
-# Returns:
-#     - nothing on success
+# Errors:
 #     - If @device is not a valid block device, DeviceNotFound
 #
 # Since: 0.14
@@ -1674,8 +1673,7 @@
 #
 # For the arguments, see the documentation of BlockdevSnapshotSync.
 #
-# Returns:
-#     - nothing on success
+# Errors:
 #     - If @device is not a valid block device, DeviceNotFound
 #
 # Since: 0.14
@@ -1754,8 +1752,7 @@
 #     is not validated, so care should be taken when specifying the
 #     string or the image chain may not be able to be reopened again.
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - If "device" does not exist or cannot be determined,
 #       DeviceNotFound
 #
@@ -1854,8 +1851,7 @@
 # @deprecated: Members @base and @top are deprecated.  Use @base-node
 #     and @top-node instead.
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - If @device does not exist, DeviceNotFound
 #     - Any other error returns a GenericError.
 #
@@ -1894,8 +1890,7 @@
 # @deprecated: This command is deprecated.  Use @blockdev-backup
 #     instead.
 #
-# Returns:
-#     - nothing on success
+# Errors:
 #     - If @device is not a valid block device, GenericError
 #
 # Since: 1.6
@@ -1921,8 +1916,7 @@
 # 'backup'. The operation can be stopped before it has completed using
 # the block-job-cancel command.
 #
-# Returns:
-#     - nothing on success
+# Errors:
 #     - If @device is not a valid block device, DeviceNotFound
 #
 # Since: 2.3
@@ -2127,8 +2121,7 @@
 # specifies the format of the mirror image, default is to probe if
 # mode='existing', else the format of the source.
 #
-# Returns:
-#     - nothing on success
+# Errors:
 #     - If @device is not a valid block device, GenericError
 #
 # Since: 1.3
@@ -2304,8 +2297,7 @@
 # Create a dirty bitmap with a name on the node, and start tracking
 # the writes.
 #
-# Returns:
-#     - nothing on success
+# Errors:
 #     - If @node is not a valid block device or node, DeviceNotFound
 #     - If @name is already taken, GenericError with an explanation
 #
@@ -2328,8 +2320,7 @@
 # with block-dirty-bitmap-add.  If the bitmap is persistent, remove it
 # from its storage too.
 #
-# Returns:
-#     - nothing on success
+# Errors:
 #     - If @node is not a valid block device or node, DeviceNotFound
 #     - If @name is not found, GenericError with an explanation
 #     - if @name is frozen by an operation, GenericError
@@ -2353,8 +2344,7 @@
 # backup from this point in time forward will only backup clusters
 # modified after this clear operation.
 #
-# Returns:
-#     - nothing on success
+# Errors:
 #     - If @node is not a valid block device, DeviceNotFound
 #     - If @name is not found, GenericError with an explanation
 #
@@ -2375,8 +2365,7 @@
 #
 # Enables a dirty bitmap so that it will begin tracking disk changes.
 #
-# Returns:
-#     - nothing on success
+# Errors:
 #     - If @node is not a valid block device, DeviceNotFound
 #     - If @name is not found, GenericError with an explanation
 #
@@ -2397,8 +2386,7 @@
 #
 # Disables a dirty bitmap so that it will stop tracking disk changes.
 #
-# Returns:
-#     - nothing on success
+# Errors:
 #     - If @node is not a valid block device, DeviceNotFound
 #     - If @name is not found, GenericError with an explanation
 #
@@ -2427,8 +2415,7 @@
 # dirty in any of the source bitmaps.  This can be used to achieve
 # backup checkpoints, or in simpler usages, to copy bitmaps.
 #
-# Returns:
-#     - nothing on success
+# Errors:
 #     - If @node is not a valid block device, DeviceNotFound
 #     - If any bitmap in @bitmaps or @target is not found,
 #       GenericError
@@ -2470,7 +2457,9 @@
 # @unstable: This command is meant for debugging.
 #
 # Returns:
-#     - BlockDirtyBitmapSha256 on success
+#     BlockDirtyBitmapSha256
+#
+# Errors:
 #     - If @node is not a valid block device, DeviceNotFound
 #     - If @name is not found or if hashing has failed, GenericError
 #       with an explanation
@@ -2542,8 +2531,6 @@
 #     disappear from the query list without user intervention.
 #     Defaults to true.  (Since 3.1)
 #
-# Returns: nothing on success.
-#
 # Since: 2.6
 #
 # Example:
@@ -2866,8 +2853,7 @@
 #     disappear from the query list without user intervention.
 #     Defaults to true.  (Since 3.1)
 #
-# Returns:
-#     - Nothing on success.
+# Errors:
 #     - If @device does not exist, DeviceNotFound.
 #
 # Since: 1.1
@@ -2905,8 +2891,7 @@
 # @speed: the maximum speed, in bytes per second, or 0 for unlimited.
 #     Defaults to 0.
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - If no background operation is active on this device,
 #       DeviceNotActive
 #
@@ -2950,8 +2935,7 @@
 #     paused) instead of waiting for the destination to complete its
 #     final synchronization (since 1.3)
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - If no background operation is active on this device,
 #       DeviceNotActive
 #
@@ -2977,8 +2961,7 @@
 #     the name of the parameter), but since QEMU 2.7 it can have other
 #     values.
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - If no background operation is active on this device,
 #       DeviceNotActive
 #
@@ -3002,8 +2985,7 @@
 #     the name of the parameter), but since QEMU 2.7 it can have other
 #     values.
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - If no background operation is active on this device,
 #       DeviceNotActive
 #
@@ -3034,8 +3016,7 @@
 #     the name of the parameter), but since QEMU 2.7 it can have other
 #     values.
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - If no background operation is active on this device,
 #       DeviceNotActive
 #
@@ -3059,8 +3040,6 @@
 #
 # @id: The job identifier.
 #
-# Returns: Nothing on success
-#
 # Since: 2.12
 ##
 { 'command': 'block-job-dismiss', 'data': { 'id': 'str' },
@@ -3078,8 +3057,6 @@
 #
 # @id: The job identifier.
 #
-# Returns: Nothing on success
-#
 # Since: 2.12
 ##
 { 'command': 'block-job-finalize', 'data': { 'id': 'str' },
@@ -6070,8 +6047,7 @@
 # For the arguments, see the documentation of
 # BlockdevSnapshotInternal.
 #
-# Returns:
-#     - nothing on success
+# Errors:
 #     - If @device is not a valid block device, GenericError
 #     - If any snapshot matching @name exists, or @name is empty,
 #       GenericError
@@ -6108,7 +6084,9 @@
 # @name: optional the snapshot's name to be deleted
 #
 # Returns:
-#     - SnapshotInfo on success
+#     SnapshotInfo
+#
+# Errors:
 #     - If @device is not a valid block device, GenericError
 #     - If snapshot not found, GenericError
 #     - If the format of the image used does not support it,
diff --git a/qapi/block-export.json b/qapi/block-export.json
index d9bd376..3919a2d 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -65,7 +65,8 @@
 #     server from advertising multiple client support (since 5.2;
 #     default: 0).
 #
-# Returns: error if the server is already running.
+# Errors:
+#     - if the server is already running
 #
 # Since: 1.3
 ##
@@ -247,8 +248,9 @@
 # @deprecated: This command is deprecated.  Use @block-export-add
 #     instead.
 #
-# Returns: error if the server is not running, or export with the same
-#     name already exists.
+# Errors:
+#     - if the server is not running
+#     - if an export with the same name already exists
 #
 # Since: 1.3
 ##
@@ -294,11 +296,10 @@
 # @deprecated: This command is deprecated.  Use @block-export-del
 #     instead.
 #
-# Returns: error if
-#
-#     - the server is not running
-#     - export is not found
-#     - mode is 'safe' and there are existing connections
+# Errors:
+#     - if the server is not running
+#     - if export is not found
+#     - if mode is 'safe' and there are existing connections
 #
 # Since: 2.12
 ##
@@ -415,8 +416,10 @@
 # @mode: Mode of command operation.  See @BlockExportRemoveMode
 #     description.  Default is 'safe'.
 #
-# Returns: Error if the export is not found or @mode is 'safe' and the
-#     export is still in use (e.g. by existing client connections)
+# Errors:
+#     - if the export is not found
+#     - if @mode is 'safe' and the export is still in use (e.g. by
+#       existing client connections)
 #
 # Since: 5.2
 ##
diff --git a/qapi/block.json b/qapi/block.json
index 79a0bcc..65d9804 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -110,8 +110,7 @@
 #
 # @deprecated: Member @device is deprecated.  Use @id instead.
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - If @device is not a valid block device, DeviceNotFound
 #
 # Notes: Ejecting a device with no media results in success
@@ -459,8 +458,7 @@
 # the device will be removed from its group and the rest of its
 # members will not be affected.  The 'group' parameter is ignored.
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - If @device is not a valid block device, DeviceNotFound
 #
 # Since: 1.1
@@ -540,8 +538,8 @@
 # @boundaries-flush: list of interval boundary values for flush
 #     latency histogram.
 #
-# Returns: error if device is not found or any boundary arrays are
-#     invalid.
+# Errors:
+#     - if device is not found or any boundary arrays are invalid.
 #
 # Since: 4.0
 #
diff --git a/qapi/char.json b/qapi/char.json
index 4873bc6..777dde5 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -139,8 +139,6 @@
 #     - data itself is always Unicode regardless of format, like any
 #       other string.
 #
-# Returns: Nothing on success
-#
 # Since: 1.4
 #
 # Example:
@@ -772,8 +770,6 @@
 #
 # @id: the chardev's ID, must exist and not be in use
 #
-# Returns: Nothing on success
-#
 # Since: 1.4
 #
 # Example:
@@ -791,8 +787,6 @@
 #
 # @id: the chardev's ID, must exist
 #
-# Returns: Nothing on success
-#
 # Since: 2.10
 #
 # Example:
diff --git a/qapi/dump.json b/qapi/dump.json
index f82dd6a..4c021dd 100644
--- a/qapi/dump.json
+++ b/qapi/dump.json
@@ -92,8 +92,6 @@
 #
 # Note: All boolean arguments default to false
 #
-# Returns: nothing on success
-#
 # Since: 1.2
 #
 # Example:
diff --git a/qapi/machine-target.json b/qapi/machine-target.json
index 2c5dda7..519adf3 100644
--- a/qapi/machine-target.json
+++ b/qapi/machine-target.json
@@ -154,10 +154,13 @@
 # Some architectures may not support comparing CPU models.  s390x
 # supports comparing CPU models.
 #
-# Returns: a CpuModelBaselineInfo.  Returns an error if comparing CPU
-#     models is not supported, if a model cannot be used, if a model
-#     contains an unknown cpu definition name, unknown properties or
-#     properties with wrong types.
+# Returns: a CpuModelBaselineInfo
+#
+# Errors:
+#     - if comparing CPU models is not supported
+#     - if a model cannot be used
+#     - if a model contains an unknown cpu definition name, unknown
+#       properties or properties with wrong types.
 #
 # Note: this command isn't specific to s390x, but is only implemented
 #     on this architecture currently.
@@ -201,10 +204,13 @@
 # Some architectures may not support baselining CPU models.  s390x
 # supports baselining CPU models.
 #
-# Returns: a CpuModelBaselineInfo.  Returns an error if baselining CPU
-#     models is not supported, if a model cannot be used, if a model
-#     contains an unknown cpu definition name, unknown properties or
-#     properties with wrong types.
+# Returns: a CpuModelBaselineInfo
+#
+# Errors:
+#     - if baselining CPU models is not supported
+#     - if a model cannot be used
+#     - if a model contains an unknown cpu definition name, unknown
+#       properties or properties with wrong types.
 #
 # Note: this command isn't specific to s390x, but is only implemented
 #     on this architecture currently.
@@ -263,11 +269,14 @@
 # Some architectures may not support all expansion types.  s390x
 # supports "full" and "static". Arm only supports "full".
 #
-# Returns: a CpuModelExpansionInfo.  Returns an error if expanding CPU
-#     models is not supported, if the model cannot be expanded, if the
-#     model contains an unknown CPU definition name, unknown
-#     properties or properties with a wrong type.  Also returns an
-#     error if an expansion type is not supported.
+# Returns: a CpuModelExpansionInfo
+#
+# Errors:
+#     - if expanding CPU models is not supported
+#     - if the model cannot be expanded
+#     - if the model contains an unknown CPU definition name, unknown
+#       properties or properties with a wrong type
+#     - if an expansion type is not supported
 #
 # Since: 2.8
 ##
@@ -405,8 +414,6 @@
 #
 # @unstable: This command is experimental.
 #
-# Returns: Nothing on success.
-#
 # Since: 8.2
 ##
 { 'command': 'set-cpu-topology',
diff --git a/qapi/machine.json b/qapi/machine.json
index 93b4677..bb5a178 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -326,8 +326,6 @@
 #
 # Since: 1.1
 #
-# Returns: nothing.
-#
 # Note: prior to 4.0, this command does nothing in case the guest
 #     isn't suspended.
 #
@@ -377,8 +375,6 @@
 # all CPUs (ppc64). The command fails when the guest doesn't support
 # injecting.
 #
-# Returns: If successful, nothing
-#
 # Since: 0.14
 #
 # Note: prior to 2.1, this command was only supported for x86 and s390
@@ -778,8 +774,6 @@
 # @cpu-index: the index of the virtual CPU to use for translating the
 #     virtual address (defaults to CPU 0)
 #
-# Returns: Nothing on success
-#
 # Since: 0.14
 #
 # Notes: Errors were not reliably returned until 1.1
@@ -806,8 +800,6 @@
 #
 # @filename: the file to save the memory to as binary data
 #
-# Returns: Nothing on success
-#
 # Since: 0.14
 #
 # Notes: Errors were not reliably returned until 1.1
@@ -1060,8 +1052,7 @@
 #
 #     From it we have: balloon_size = vm_ram_size - @value
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - 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
@@ -1099,7 +1090,9 @@
 # Return information about the balloon device.
 #
 # Returns:
-#     - @BalloonInfo on success
+#     @BalloonInfo
+#
+# Errors:
 #     - 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
@@ -1163,7 +1156,9 @@
 # message from the guest.
 #
 # Returns:
-#     - @HvBalloonInfo on success
+#     @HvBalloonInfo
+#
+# Errors:
 #     - If no hv-balloon device is present, guest memory status
 #       reporting is not enabled or no guest memory status report
 #       received yet, GenericError
diff --git a/qapi/migration.json b/qapi/migration.json
index 62acc83..51d188b 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -1572,8 +1572,6 @@
 #
 # Cancel the current executing migration process.
 #
-# Returns: nothing on success
-#
 # Notes: This command succeeds even if there is no migration process
 #     running.
 #
@@ -1593,8 +1591,6 @@
 #
 # @state: The state the migration is currently expected to be in
 #
-# Returns: nothing on success
-#
 # Since: 2.11
 #
 # Example:
@@ -1716,8 +1712,6 @@
 # @deprecated: Members @inc and @blk are deprecated.  Use
 #     blockdev-mirror with NBD instead.
 #
-# Returns: nothing on success
-#
 # Since: 0.14
 #
 # Notes:
@@ -1799,8 +1793,6 @@
 # @channels: list of migration stream channels with each stream in the
 #     list connected to a destination interface endpoint.
 #
-# Returns: nothing on success
-#
 # Since: 2.3
 #
 # Notes:
@@ -1868,8 +1860,6 @@
 # @live: Optional argument to ask QEMU to treat this command as part
 #     of a live migration.  Default to true.  (since 2.11)
 #
-# Returns: Nothing on success
-#
 # Since: 1.1
 #
 # Example:
@@ -1888,8 +1878,6 @@
 #
 # @enable: true to enable, false to disable.
 #
-# Returns: nothing
-#
 # Since: 1.3
 #
 # Example:
@@ -1932,8 +1920,6 @@
 # @failover: true to do failover, false to stop.  but cannot be
 #     specified if 'enable' is true.  default value is false.
 #
-# Returns: nothing.
-#
 # Example:
 #
 #     -> { "execute": "xen-set-replication",
@@ -1985,8 +1971,6 @@
 #
 # Xen uses this command to notify replication to trigger a checkpoint.
 #
-# Returns: nothing.
-#
 # Example:
 #
 #     -> { "execute": "xen-colo-do-checkpoint" }
@@ -2043,8 +2027,6 @@
 #
 # @uri: the URI to be used for the recovery of migration stream.
 #
-# Returns: nothing.
-#
 # Example:
 #
 #     -> { "execute": "migrate-recover",
@@ -2062,8 +2044,6 @@
 #
 # Pause a migration.  Currently it only supports postcopy.
 #
-# Returns: nothing.
-#
 # Example:
 #
 #     -> { "execute": "migrate-pause" }
@@ -2432,8 +2412,6 @@
 #
 # If @tag already exists, an error will be reported
 #
-# Returns: nothing
-#
 # Example:
 #
 #     -> { "execute": "snapshot-save",
@@ -2504,8 +2482,6 @@
 # device nodes that can have changed since the original @snapshot-save
 # command execution.
 #
-# Returns: nothing
-#
 # Example:
 #
 #     -> { "execute": "snapshot-load",
@@ -2567,8 +2543,6 @@
 # to determine completion and to fetch details of any errors that
 # arise.
 #
-# Returns: nothing
-#
 # Example:
 #
 #     -> { "execute": "snapshot-delete",
diff --git a/qapi/misc-target.json b/qapi/misc-target.json
index 542a3e4..4e0a649 100644
--- a/qapi/misc-target.json
+++ b/qapi/misc-target.json
@@ -472,9 +472,6 @@
 #
 # @port: The port number
 #
-# Returns:
-#     - Nothing on success.
-#
 # Since: 8.0
 #
 # Example:
diff --git a/qapi/misc.json b/qapi/misc.json
index 11c55c2..1b0c5da 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -28,8 +28,6 @@
 #
 # @tls: whether to perform TLS. Only applies to the "spice" protocol
 #
-# Returns: nothing on success.
-#
 # Since: 0.14
 #
 # Example:
@@ -160,8 +158,6 @@
 #
 # Since: 0.14
 #
-# Returns: If successful, nothing
-#
 # Notes: This command will succeed if the guest is currently running.
 #     It will also succeed if the guest is in the "inmigrate" state;
 #     in this case, the effect of the command is to make sure the
@@ -196,8 +192,6 @@
 #
 # Since: 3.0
 #
-# Returns: nothing
-#
 # Example:
 #
 #     -> { "execute": "x-exit-preconfig" }
@@ -256,8 +250,6 @@
 #
 # @fdname: file descriptor name
 #
-# Returns: Nothing on success
-#
 # Since: 0.14
 #
 # Notes: If @fdname already exists, the file descriptor assigned to it
@@ -285,8 +277,6 @@
 #
 # @fdname: file descriptor name
 #
-# Returns: Nothing on success
-#
 # Since: 8.0
 #
 # Notes: If @fdname already exists, the file descriptor assigned to it
@@ -309,8 +299,6 @@
 #
 # @fdname: file descriptor name
 #
-# Returns: Nothing on success
-#
 # Since: 0.14
 #
 # Example:
@@ -344,7 +332,9 @@
 # @opaque: A free-form string that can be used to describe the fd.
 #
 # Returns:
-#     - @AddfdInfo on success
+#     @AddfdInfo
+#
+# Errors:
 #     - If file descriptor was not received, GenericError
 #     - If @fdset-id is a negative value, GenericError
 #
@@ -374,8 +364,7 @@
 #
 # @fd: The file descriptor that is to be removed.
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - If @fdset-id or @fd is not found, GenericError
 #
 # Since: 1.2
@@ -528,8 +517,10 @@
 # @option: option name
 #
 # Returns: list of @CommandLineOptionInfo for all options (or for the
-#     given @option).  Returns an error if the given @option doesn't
-#     exist.
+#     given @option).
+#
+# Errors:
+#     - if the given @option doesn't exist
 #
 # Since: 1.5
 #
diff --git a/qapi/net.json b/qapi/net.json
index 1374caa..417b61a 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -17,8 +17,7 @@
 #
 # @up: true to set the link status to be up
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - If @name is not a valid network device, DeviceNotFound
 #
 # Since: 0.14
@@ -44,8 +43,7 @@
 #
 # Since: 0.14
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - If @type is not a valid network backend, DeviceNotFound
 #
 # Example:
@@ -65,8 +63,7 @@
 #
 # @id: the name of the network backend to remove
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - If @id is not a valid network backend, DeviceNotFound
 #
 # Since: 0.14
@@ -828,9 +825,11 @@
 # @name: net client name
 #
 # Returns: list of @RxFilterInfo for all NICs (or for the given NIC).
-#     Returns an error if the given @name doesn't exist, or given NIC
-#     doesn't support rx-filter querying, or given net client isn't a
-#     NIC.
+#
+# Errors:
+#     - if the given @name doesn't exist
+#     - if the given NIC doesn't support rx-filter querying
+#     - if the given net client isn't a NIC
 #
 # Since: 1.6
 #
diff --git a/qapi/qapi-type-helpers.c b/qapi/qapi-type-helpers.c
index f76b34f..266da01 100644
--- a/qapi/qapi-type-helpers.c
+++ b/qapi/qapi-type-helpers.c
@@ -21,3 +21,17 @@ HumanReadableText *human_readable_text_from_str(GString *str)
 
     return ret;
 }
+
+char **strv_from_str_list(const strList *list)
+{
+    const strList *tail;
+    int i = 0;
+    char **strv = g_new(char *, QAPI_LIST_LENGTH(list) + 1);
+
+    for (tail = list; tail != NULL; tail = tail->next) {
+        strv[i++] = g_strdup(tail->value);
+    }
+    strv[i] = NULL;
+
+    return strv;
+}
diff --git a/qapi/qdev.json b/qapi/qdev.json
index 32ffaee..facaa0b 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -89,8 +89,7 @@
 #
 # @id: the device's ID or QOM path
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - If @id is not a valid device, DeviceNotFound
 #
 # Notes: When this command completes, the device may not be removed
diff --git a/qapi/qom.json b/qapi/qom.json
index 2a6e493..032c6fa 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -1056,8 +1056,7 @@
 #
 # Create a QOM object.
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - Error if @qom-type is not a valid class name
 #
 # Since: 2.0
@@ -1079,8 +1078,7 @@
 #
 # @id: the name of the QOM object to remove
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - Error if @id is not a valid id for a QOM object
 #
 # Since: 2.0
diff --git a/qapi/run-state.json b/qapi/run-state.json
index dd0770b..789fc34 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -395,10 +395,7 @@
 #
 # @panic: @PanicAction action taken on guest panic.
 #
-# @watchdog: @WatchdogAction action taken when watchdog timer expires
-#     .
-#
-# Returns: Nothing on success.
+# @watchdog: @WatchdogAction action taken when watchdog timer expires.
 #
 # Since: 6.0
 #
diff --git a/qapi/tpm.json b/qapi/tpm.json
index 07a73e5..1577b5c 100644
--- a/qapi/tpm.json
+++ b/qapi/tpm.json
@@ -166,8 +166,6 @@
 #
 # Return information about the TPM device
 #
-# Returns: @TPMInfo on success
-#
 # Since: 1.5
 #
 # Example:
diff --git a/qapi/transaction.json b/qapi/transaction.json
index 45233dd..5749c13 100644
--- a/qapi/transaction.json
+++ b/qapi/transaction.json
@@ -234,9 +234,8 @@
 #     execution of the transaction.  See @TransactionProperties for
 #     additional detail.
 #
-# Returns: nothing on success
-#
-#     Errors depend on the operations of the transaction
+# Errors:
+#     Any errors from commands in the transaction
 #
 # Note: The transaction aborts on the first failure.  Therefore, there
 #     will be information on only one failed operation returned in an
diff --git a/qapi/ui.json b/qapi/ui.json
index e3999b7..1726f15 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -78,8 +78,7 @@
 #
 # Set the password of a remote display server.
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - If Spice is not enabled, DeviceNotFound
 #
 # Since: 0.14
@@ -140,8 +139,7 @@
 #
 # Expire the password of a remote display server.
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - If @protocol is 'spice' and Spice is not active,
 #       DeviceNotFound
 #
@@ -187,8 +185,6 @@
 #
 # @format: image format for screendump.  (default: ppm) (Since 7.1)
 #
-# Returns: Nothing on success
-#
 # Since: 0.14
 #
 # Example:
@@ -1036,8 +1032,7 @@
 # @hold-time: time to delay key up events, milliseconds.  Defaults to
 #     100
 #
-# Returns:
-#     - Nothing on success
+# Errors:
 #     - If key is unknown or redundant, GenericError
 #
 # Since: 1.3
@@ -1259,8 +1254,6 @@
 #
 # @events: List of InputEvent union.
 #
-# Returns: Nothing on success.
-#
 # Since: 2.6
 #
 # Note: The consoles are visible in the qom tree, under
@@ -1605,8 +1598,6 @@
 #
 # Reload display configuration.
 #
-# Returns: Nothing on success.
-#
 # Since: 6.0
 #
 # Example:
@@ -1664,8 +1655,6 @@
 #
 # Update display configuration.
 #
-# Returns: Nothing on success.
-#
 # Since: 7.1
 #
 # Example:
diff --git a/qapi/yank.json b/qapi/yank.json
index b7aeb9c..89f2f4d 100644
--- a/qapi/yank.json
+++ b/qapi/yank.json
@@ -78,9 +78,8 @@
 #
 # @instances: the instances to be yanked
 #
-# Returns:
-#     - Nothing on success
-#     - @DeviceNotFound error, if any of the YankInstances doesn't exist
+# Errors:
+#     - If any of the YankInstances doesn't exist, DeviceNotFound
 #
 # Example:
 #