qapi: Move error documentation to new "Errors" sections

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240227113921.236097-5-armbru@redhat.com>

qapi/block-core.json

@@ -1458,6 +1458,8 @@
 #
 # Returns:
 #     - nothing on success
+#
+# Errors:
 #     - If @device is not a valid block device, DeviceNotFound
 #
 # Since: 0.14
@@ -1676,6 +1678,8 @@
 #
 # Returns:
 #     - nothing on success
+#
+# Errors:
 #     - If @device is not a valid block device, DeviceNotFound
 #
 # Since: 0.14
@@ -1756,6 +1760,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - If "device" does not exist or cannot be determined,
 #       DeviceNotFound
 #
@@ -1856,6 +1862,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - If @device does not exist, DeviceNotFound
 #     - Any other error returns a GenericError.
 #
@@ -1896,6 +1904,8 @@
 #
 # Returns:
 #     - nothing on success
+#
+# Errors:
 #     - If @device is not a valid block device, GenericError
 #
 # Since: 1.6
@@ -1923,6 +1933,8 @@
 #
 # Returns:
 #     - nothing on success
+#
+# Errors:
 #     - If @device is not a valid block device, DeviceNotFound
 #
 # Since: 2.3
@@ -2129,6 +2141,8 @@
 #
 # Returns:
 #     - nothing on success
+#
+# Errors:
 #     - If @device is not a valid block device, GenericError
 #
 # Since: 1.3
@@ -2306,6 +2320,8 @@
 #
 # 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
 #
@@ -2330,6 +2346,8 @@
 #
 # 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
@@ -2355,6 +2373,8 @@
 #
 # Returns:
 #     - nothing on success
+#
+# Errors:
 #     - If @node is not a valid block device, DeviceNotFound
 #     - If @name is not found, GenericError with an explanation
 #
@@ -2377,6 +2397,8 @@
 #
 # Returns:
 #     - nothing on success
+#
+# Errors:
 #     - If @node is not a valid block device, DeviceNotFound
 #     - If @name is not found, GenericError with an explanation
 #
@@ -2399,6 +2421,8 @@
 #
 # Returns:
 #     - nothing on success
+#
+# Errors:
 #     - If @node is not a valid block device, DeviceNotFound
 #     - If @name is not found, GenericError with an explanation
 #
@@ -2429,6 +2453,8 @@
 #
 # 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
@@ -2471,6 +2497,8 @@
 #
 # Returns:
 #     - BlockDirtyBitmapSha256 on success
+#
+# Errors:
 #     - If @node is not a valid block device, DeviceNotFound
 #     - If @name is not found or if hashing has failed, GenericError
 #       with an explanation
@@ -2868,6 +2896,8 @@
 #
 # Returns:
 #     - Nothing on success.
+#
+# Errors:
 #     - If @device does not exist, DeviceNotFound.
 #
 # Since: 1.1
@@ -2907,6 +2937,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - If no background operation is active on this device,
 #       DeviceNotActive
 #
@@ -2952,6 +2984,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - If no background operation is active on this device,
 #       DeviceNotActive
 #
@@ -2979,6 +3013,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - If no background operation is active on this device,
 #       DeviceNotActive
 #
@@ -3004,6 +3040,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - If no background operation is active on this device,
 #       DeviceNotActive
 #
@@ -3036,6 +3074,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - If no background operation is active on this device,
 #       DeviceNotActive
 #
@@ -6072,6 +6112,8 @@
 #
 # 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
@@ -6109,6 +6151,8 @@
 #
 # Returns:
 #     - SnapshotInfo on success
+#
+# 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,

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
+# Errors:
-#     name already exists.
+#     - 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
+# Errors:
-#
+#     - if the server is not running
-#     - the server is not running
+#     - if export is not found
-#     - export is not found
+#     - if mode is 'safe' and there are existing connections
-#     - 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
+# Errors:
-#     export is still in use (e.g. by existing client connections)
+#     - 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
 ##

qapi/block.json

@@ -112,6 +112,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - If @device is not a valid block device, DeviceNotFound
 #
 # Notes: Ejecting a device with no media results in success
@@ -461,6 +463,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - If @device is not a valid block device, DeviceNotFound
 #
 # Since: 1.1
@@ -540,8 +544,8 @@
 # @boundaries-flush: list of interval boundary values for flush
 #     latency histogram.
 #
-# Returns: error if device is not found or any boundary arrays are
+# Errors:
-#     invalid.
+#     - if device is not found or any boundary arrays are invalid.
 #
 # Since: 4.0
 #

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
+# Returns: a CpuModelBaselineInfo
-#     models is not supported, if a model cannot be used, if a model
+#
-#     contains an unknown cpu definition name, unknown properties or
+# Errors:
-#     properties with wrong types.
+#     - 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
+# Returns: a CpuModelBaselineInfo
-#     models is not supported, if a model cannot be used, if a model
+#
-#     contains an unknown cpu definition name, unknown properties or
+# Errors:
-#     properties with wrong types.
+#     - 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
+# Returns: a CpuModelExpansionInfo
-#     models is not supported, if the model cannot be expanded, if the
+#
-#     model contains an unknown CPU definition name, unknown
+# Errors:
-#     properties or properties with a wrong type.  Also returns an
+#     - if expanding CPU models is not supported
-#     error if an expansion type 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
 ##

qapi/machine.json

@@ -1062,6 +1062,8 @@
 #
 # 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
@@ -1100,6 +1102,8 @@
 #
 # Returns:
 #     - @BalloonInfo 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
@@ -1164,6 +1168,8 @@
 #
 # Returns:
 #     - @HvBalloonInfo on success
+#
+# Errors:
 #     - If no hv-balloon device is present, guest memory status
 #       reporting is not enabled or no guest memory status report
 #       received yet, GenericError

qapi/misc.json

@@ -345,6 +345,8 @@
 #
 # Returns:
 #     - @AddfdInfo on success
+#
+# Errors:
 #     - If file descriptor was not received, GenericError
 #     - If @fdset-id is a negative value, GenericError
 #
@@ -376,6 +378,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - If @fdset-id or @fd is not found, GenericError
 #
 # Since: 1.2
@@ -528,8 +532,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
+#     given @option).
-#     exist.
+#
+# Errors:
+#     - if the given @option doesn't exist
 #
 # Since: 1.5
 #

qapi/net.json

@@ -19,6 +19,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - If @name is not a valid network device, DeviceNotFound
 #
 # Since: 0.14
@@ -46,6 +48,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - If @type is not a valid network backend, DeviceNotFound
 #
 # Example:
@@ -67,6 +71,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - If @id is not a valid network backend, DeviceNotFound
 #
 # Since: 0.14
@@ -828,9 +834,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
+# Errors:
-#     NIC.
+#     - 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
 #

qapi/qdev.json

@@ -91,6 +91,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - If @id is not a valid device, DeviceNotFound
 #
 # Notes: When this command completes, the device may not be removed

qapi/qom.json

@@ -1058,6 +1058,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - Error if @qom-type is not a valid class name
 #
 # Since: 2.0
@@ -1081,6 +1083,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - Error if @id is not a valid id for a QOM object
 #
 # Since: 2.0

qapi/transaction.json

@@ -236,7 +236,8 @@
 #
 # 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

qapi/ui.json

@@ -80,6 +80,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - If Spice is not enabled, DeviceNotFound
 #
 # Since: 0.14
@@ -142,6 +144,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - If @protocol is 'spice' and Spice is not active,
 #       DeviceNotFound
 #
@@ -1038,6 +1042,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - If key is unknown or redundant, GenericError
 #
 # Since: 1.3

qapi/yank.json

@@ -80,6 +80,8 @@
 #
 # Returns:
 #     - Nothing on success
+#
+# Errors:
 #     - @DeviceNotFound error, if any of the YankInstances doesn't exist
 #
 # Example: