From e050e426782ec4ae6bf84e5ec75ca502187f69cb Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Thu, 13 Feb 2020 17:56:30 +0000 Subject: [PATCH] qapi: Use explicit bulleted lists A JSON block comment like this: Returns: nothing on success If @node is not a valid block device, DeviceNotFound If @name is not found, GenericError with an explanation renders like this: Returns: nothing on success If node is not a valid block device, DeviceNotFound If name is not found, GenericError with an explanation because whitespace is not significant. Use an actual bulleted list, so that the formatting is correct. Signed-off-by: Peter Maydell Message-Id: <20200213175647.17628-14-peter.maydell@linaro.org> Message-Id: <20200213175647.17628-15-peter.maydell@linaro.org> Message-Id: <20200213175647.17628-16-peter.maydell@linaro.org> [Three commits squashed into one] Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/block-core.json | 108 +++++++++++++++++++++---------------------- qapi/block.json | 33 ++++++------- qapi/misc.json | 36 +++++++-------- qapi/tpm.json | 4 +- qapi/ui.json | 63 +++++++++++++------------ 5 files changed, 119 insertions(+), 125 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 31f7a1281c..082aca3f69 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -1326,8 +1326,8 @@ # # @size: new image size in bytes # -# Returns: nothing on success -# If @device is not a valid block device, DeviceNotFound +# Returns: - nothing on success +# - If @device is not a valid block device, DeviceNotFound # # Since: 0.14.0 # @@ -1510,8 +1510,8 @@ # # For the arguments, see the documentation of BlockdevSnapshotSync. # -# Returns: nothing on success -# If @device is not a valid block device, DeviceNotFound +# Returns: - nothing on success +# - If @device is not a valid block device, DeviceNotFound # # Since: 0.14.0 # @@ -1586,9 +1586,8 @@ # when specifying the string or the image chain may # not be able to be reopened again. # -# Returns: Nothing on success -# -# If "device" does not exist or cannot be determined, DeviceNotFound +# Returns: - Nothing on success +# - If "device" does not exist or cannot be determined, DeviceNotFound # # Since: 2.1 ## @@ -1674,9 +1673,9 @@ # list without user intervention. # Defaults to true. (Since 3.1) # -# Returns: Nothing on success -# If @device does not exist, DeviceNotFound -# Any other error returns a GenericError. +# Returns: - Nothing on success +# - If @device does not exist, DeviceNotFound +# - Any other error returns a GenericError. # # Since: 1.3 # @@ -1704,8 +1703,8 @@ # The operation can be stopped before it has completed using the # block-job-cancel command. # -# Returns: nothing on success -# If @device is not a valid block device, GenericError +# Returns: - nothing on success +# - If @device is not a valid block device, GenericError # # Since: 1.6 # @@ -1730,8 +1729,8 @@ # The operation can be stopped before it has completed using the # block-job-cancel command. # -# Returns: nothing on success -# If @device is not a valid block device, DeviceNotFound +# Returns: - nothing on success +# - If @device is not a valid block device, DeviceNotFound # # Since: 2.3 # @@ -1925,8 +1924,8 @@ # format of the mirror image, default is to probe if mode='existing', # else the format of the source. # -# Returns: nothing on success -# If @device is not a valid block device, GenericError +# Returns: - nothing on success +# - If @device is not a valid block device, GenericError # # Since: 1.3 # @@ -2097,9 +2096,9 @@ # # Create a dirty bitmap with a name on the node, and start tracking the writes. # -# Returns: nothing on success -# If @node is not a valid block device or node, DeviceNotFound -# If @name is already taken, GenericError with an explanation +# Returns: - nothing on success +# - If @node is not a valid block device or node, DeviceNotFound +# - If @name is already taken, GenericError with an explanation # # Since: 2.4 # @@ -2120,10 +2119,10 @@ # with block-dirty-bitmap-add. If the bitmap is persistent, remove it from its # storage too. # -# Returns: nothing on success -# 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 +# Returns: - nothing on success +# - 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 # # Since: 2.4 # @@ -2144,9 +2143,9 @@ # backup from this point in time forward will only backup clusters # modified after this clear operation. # -# Returns: nothing on success -# If @node is not a valid block device, DeviceNotFound -# If @name is not found, GenericError with an explanation +# Returns: - nothing on success +# - If @node is not a valid block device, DeviceNotFound +# - If @name is not found, GenericError with an explanation # # Since: 2.4 # @@ -2165,9 +2164,9 @@ # # Enables a dirty bitmap so that it will begin tracking disk changes. # -# Returns: nothing on success -# If @node is not a valid block device, DeviceNotFound -# If @name is not found, GenericError with an explanation +# Returns: - nothing on success +# - If @node is not a valid block device, DeviceNotFound +# - If @name is not found, GenericError with an explanation # # Since: 4.0 # @@ -2186,9 +2185,9 @@ # # Disables a dirty bitmap so that it will stop tracking disk changes. # -# Returns: nothing on success -# If @node is not a valid block device, DeviceNotFound -# If @name is not found, GenericError with an explanation +# Returns: - nothing on success +# - If @node is not a valid block device, DeviceNotFound +# - If @name is not found, GenericError with an explanation # # Since: 4.0 # @@ -2215,11 +2214,11 @@ # of the source bitmaps. This can be used to achieve backup checkpoints, or in # simpler usages, to copy bitmaps. # -# Returns: nothing on success -# If @node is not a valid block device, DeviceNotFound -# If any bitmap in @bitmaps or @target is not found, GenericError -# If any of the bitmaps have different sizes or granularities, -# GenericError +# Returns: - nothing on success +# - If @node is not a valid block device, DeviceNotFound +# - If any bitmap in @bitmaps or @target is not found, GenericError +# - If any of the bitmaps have different sizes or granularities, +# GenericError # # Since: 4.0 # @@ -2251,10 +2250,10 @@ # # Get bitmap SHA256. # -# Returns: BlockDirtyBitmapSha256 on success -# If @node is not a valid block device, DeviceNotFound -# If @name is not found or if hashing has failed, GenericError with an -# explanation +# Returns: - BlockDirtyBitmapSha256 on success +# - If @node is not a valid block device, DeviceNotFound +# - If @name is not found or if hashing has failed, GenericError with an +# explanation # # Since: 2.10 ## @@ -2371,8 +2370,8 @@ # 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 -# If @device is not a valid block device, DeviceNotFound +# Returns: - Nothing on success +# - If @device is not a valid block device, DeviceNotFound # # Since: 1.1 # @@ -2622,7 +2621,8 @@ # list without user intervention. # Defaults to true. (Since 3.1) # -# Returns: Nothing on success. If @device does not exist, DeviceNotFound. +# Returns: - Nothing on success. +# - If @device does not exist, DeviceNotFound. # # Since: 1.1 # @@ -2656,8 +2656,8 @@ # @speed: the maximum speed, in bytes per second, or 0 for unlimited. # Defaults to 0. # -# Returns: Nothing on success -# If no background operation is active on this device, DeviceNotActive +# Returns: - Nothing on success +# - If no background operation is active on this device, DeviceNotActive # # Since: 1.1 ## @@ -2696,8 +2696,8 @@ # abandon the job immediately (even if it is paused) instead of waiting # for the destination to complete its final synchronization (since 1.3) # -# Returns: Nothing on success -# If no background operation is active on this device, DeviceNotActive +# Returns: - Nothing on success +# - If no background operation is active on this device, DeviceNotActive # # Since: 1.1 ## @@ -2720,8 +2720,8 @@ # the name of the parameter), but since QEMU 2.7 it can have # other values. # -# Returns: Nothing on success -# If no background operation is active on this device, DeviceNotActive +# Returns: - Nothing on success +# - If no background operation is active on this device, DeviceNotActive # # Since: 1.3 ## @@ -2742,8 +2742,8 @@ # the name of the parameter), but since QEMU 2.7 it can have # other values. # -# Returns: Nothing on success -# If no background operation is active on this device, DeviceNotActive +# Returns: - Nothing on success +# - If no background operation is active on this device, DeviceNotActive # # Since: 1.3 ## @@ -2770,8 +2770,8 @@ # the name of the parameter), but since QEMU 2.7 it can have # other values. # -# Returns: Nothing on success -# If no background operation is active on this device, DeviceNotActive +# Returns: - Nothing on success +# - If no background operation is active on this device, DeviceNotActive # # Since: 1.3 ## diff --git a/qapi/block.json b/qapi/block.json index 65eaacf31a..da19834db4 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -115,15 +115,12 @@ # # For the arguments, see the documentation of BlockdevSnapshotInternal. # -# Returns: nothing on success -# -# If @device is not a valid block device, GenericError -# -# If any snapshot matching @name exists, or @name is empty, -# GenericError -# -# If the format of the image used does not support it, -# BlockFormatFeatureNotSupported +# Returns: - nothing on success +# - If @device is not a valid block device, GenericError +# - If any snapshot matching @name exists, or @name is empty, +# GenericError +# - If the format of the image used does not support it, +# BlockFormatFeatureNotSupported # # Since: 1.7 # @@ -154,12 +151,12 @@ # # @name: optional the snapshot's name to be deleted # -# Returns: SnapshotInfo on success -# 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, -# BlockFormatFeatureNotSupported -# If @id and @name are both not specified, GenericError +# Returns: - SnapshotInfo on success +# - 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, +# BlockFormatFeatureNotSupported +# - If @id and @name are both not specified, GenericError # # Since: 1.7 # @@ -197,10 +194,8 @@ # @force: If true, eject regardless of whether the drive is locked. # If not specified, the default value is false. # -# Returns: Nothing on success -# -# If @device is not a valid block device, DeviceNotFound -# +# Returns: - Nothing on success +# - If @device is not a valid block device, DeviceNotFound # Notes: Ejecting a device with no media results in success # # Since: 0.14.0 diff --git a/qapi/misc.json b/qapi/misc.json index 46e0abdfe7..af00279e7b 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -430,12 +430,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 +# 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 # # Since: 0.14.0 # @@ -492,8 +490,8 @@ # # @bar: the index of the Base Address Register for this region # -# @type: 'io' if the region is a PIO region -# 'memory' if the region is a MMIO region +# @type: - 'io' if the region is a PIO region +# - 'memory' if the region is a MMIO region # # @size: memory size # @@ -1004,10 +1002,10 @@ # # @value: the target size of the balloon in bytes # -# Returns: Nothing on success -# If the balloon driver is enabled but not functional because the KVM +# 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 +# - 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 change the balloon @@ -1086,8 +1084,8 @@ # If @device is 'vnc' and @target is 'password', this is the new VNC # password to set. See change-vnc-password for additional notes. # -# Returns: Nothing on success. -# If @device is not a valid block device, DeviceNotFound +# Returns: - Nothing on success. +# - If @device is not a valid block device, DeviceNotFound # # Notes: This interface is deprecated, and it is strongly recommended that you # avoid using it. For changing block devices, use @@ -1237,11 +1235,9 @@ # # @opaque: A free-form string that can be used to describe the fd. # -# Returns: @AddfdInfo on success -# -# If file descriptor was not received, FdNotSupplied -# -# If @fdset-id is a negative value, InvalidParameterValue +# Returns: - @AddfdInfo on success +# - If file descriptor was not received, FdNotSupplied +# - If @fdset-id is a negative value, InvalidParameterValue # # Notes: The list of fd sets is shared by all monitor connections. # @@ -1269,8 +1265,8 @@ # # @fd: The file descriptor that is to be removed. # -# Returns: Nothing on success -# If @fdset-id or @fd is not found, FdNotFound +# Returns: - Nothing on success +# - If @fdset-id or @fd is not found, FdNotFound # # Since: 1.2.0 # diff --git a/qapi/tpm.json b/qapi/tpm.json index 63878aa0f4..dc1f081739 100644 --- a/qapi/tpm.json +++ b/qapi/tpm.json @@ -96,8 +96,8 @@ # # A union referencing different TPM backend types' configuration options # -# @type: 'passthrough' The configuration options for the TPM passthrough type -# 'emulator' The configuration options for TPM emulator backend type +# @type: - 'passthrough' The configuration options for the TPM passthrough type +# - 'emulator' The configuration options for TPM emulator backend type # # Since: 1.5 ## diff --git a/qapi/ui.json b/qapi/ui.json index 088a8680ef..e4bd3d8ea7 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -12,8 +12,8 @@ # # Sets the password of a remote display session. # -# @protocol: 'vnc' to modify the VNC server password -# 'spice' to modify the Spice server password +# @protocol: - 'vnc' to modify the VNC server password +# - 'spice' to modify the Spice server password # # @password: the new password # @@ -23,8 +23,8 @@ # 'disconnect' to disconnect existing clients # 'keep' to maintain existing clients # -# Returns: Nothing on success -# If Spice is not enabled, DeviceNotFound +# Returns: - Nothing on success +# - If Spice is not enabled, DeviceNotFound # # Since: 0.14.0 # @@ -46,13 +46,14 @@ # @protocol: the name of the remote display protocol 'vnc' or 'spice' # # @time: when to expire the password. -# 'now' to expire the password immediately -# 'never' to cancel password expiration -# '+INT' where INT is the number of seconds from now (integer) -# 'INT' where INT is the absolute time in seconds # -# Returns: Nothing on success -# If @protocol is 'spice' and Spice is not active, DeviceNotFound +# - 'now' to expire the password immediately +# - 'never' to cancel password expiration +# - '+INT' where INT is the number of seconds from now (integer) +# - 'INT' where INT is the absolute time in seconds +# +# Returns: - Nothing on success +# - If @protocol is 'spice' and Spice is not active, DeviceNotFound # # Since: 0.14.0 # @@ -201,9 +202,10 @@ # @tls-port: The SPICE server's TLS port number. # # @auth: the current authentication type used by the server -# 'none' if no authentication is being used -# 'spice' uses SASL or direct TLS authentication, depending on command -# line options +# +# - 'none' if no authentication is being used +# - 'spice' uses SASL or direct TLS authentication, depending on command +# line options # # @mouse-mode: The mode in which the mouse cursor is displayed currently. Can # be determined by the client or the server, or unknown if spice @@ -433,27 +435,28 @@ # @host: The hostname the VNC server is bound to. This depends on # the name resolution on the host and may be an IP address. # -# @family: 'ipv6' if the host is listening for IPv6 connections -# 'ipv4' if the host is listening for IPv4 connections -# 'unix' if the host is listening on a unix domain socket -# 'unknown' otherwise +# @family: - 'ipv6' if the host is listening for IPv6 connections +# - 'ipv4' if the host is listening for IPv4 connections +# - 'unix' if the host is listening on a unix domain socket +# - 'unknown' otherwise # # @service: The service name of the server's port. This may depends # on the host system's service database so symbolic names should not # be relied on. # # @auth: the current authentication type used by the server -# 'none' if no authentication is being used -# 'vnc' if VNC authentication is being used -# 'vencrypt+plain' if VEncrypt is used with plain text authentication -# 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication -# 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication -# 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth -# 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth -# 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth -# 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth -# 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth -# 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth +# +# - 'none' if no authentication is being used +# - 'vnc' if VNC authentication is being used +# - 'vencrypt+plain' if VEncrypt is used with plain text authentication +# - 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication +# - 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication +# - 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth +# - 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth +# - 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth +# - 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth +# - 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth +# - 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth # # @clients: a list of @VncClientInfo of all currently connected clients # @@ -840,8 +843,8 @@ # @hold-time: time to delay key up events, milliseconds. Defaults # to 100 # -# Returns: Nothing on success -# If key is unknown or redundant, InvalidParameter +# Returns: - Nothing on success +# - If key is unknown or redundant, InvalidParameter # # Since: 1.3.0 # -- 2.39.5