OpenE2K
/
qemu-e2k
13
4
Fork 0
Code Issues 4 Pull Requests Projects 2 Releases Activity

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 <peter.maydell@linaro.org>
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 <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit is contained in:
Peter Maydell 2020-02-13 17:56:30 +00:00 committed by Markus Armbruster
parent 449be9df52
commit e050e42678
5 changed files with 119 additions and 125 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

108
qapi/block-core.json
View File

@ -1326,8 +1326,8 @@
# #
# @size: new image size in bytes # @size: new image size in bytes
# #
# Returns: nothing on success # Returns: - nothing on success
# If @device is not a valid block device, DeviceNotFound # - If @device is not a valid block device, DeviceNotFound
# #
# Since: 0.14.0 # Since: 0.14.0
# #
@ -1510,8 +1510,8 @@
# #
# For the arguments, see the documentation of BlockdevSnapshotSync. # For the arguments, see the documentation of BlockdevSnapshotSync.
# #
# Returns: nothing on success # Returns: - nothing on success
# If @device is not a valid block device, DeviceNotFound # - If @device is not a valid block device, DeviceNotFound
# #
# Since: 0.14.0 # Since: 0.14.0
# #
@ -1586,9 +1586,8 @@
# when specifying the string or the image chain may # when specifying the string or the image chain may
# not be able to be reopened again. # not be able to be reopened again.
# #
# Returns: Nothing on success # Returns: - Nothing on success
# # - If "device" does not exist or cannot be determined, DeviceNotFound
# If "device" does not exist or cannot be determined, DeviceNotFound
# #
# Since: 2.1 # Since: 2.1
## ##
@ -1674,9 +1673,9 @@
# list without user intervention. # list without user intervention.
# Defaults to true. (Since 3.1) # Defaults to true. (Since 3.1)
# #
# Returns: Nothing on success # Returns: - Nothing on success
# If @device does not exist, DeviceNotFound # - If @device does not exist, DeviceNotFound
# Any other error returns a GenericError. # - Any other error returns a GenericError.
# #
# Since: 1.3 # Since: 1.3
# #
@ -1704,8 +1703,8 @@
# The operation can be stopped before it has completed using the # The operation can be stopped before it has completed using the
# block-job-cancel command. # block-job-cancel command.
# #
# Returns: nothing on success # Returns: - nothing on success
# If @device is not a valid block device, GenericError # - If @device is not a valid block device, GenericError
# #
# Since: 1.6 # Since: 1.6
# #
@ -1730,8 +1729,8 @@
# The operation can be stopped before it has completed using the # The operation can be stopped before it has completed using the
# block-job-cancel command. # block-job-cancel command.
# #
# Returns: nothing on success # Returns: - nothing on success
# If @device is not a valid block device, DeviceNotFound # - If @device is not a valid block device, DeviceNotFound
# #
# Since: 2.3 # Since: 2.3
# #
@ -1925,8 +1924,8 @@
# format of the mirror image, default is to probe if mode='existing', # format of the mirror image, default is to probe if mode='existing',
# else the format of the source. # else the format of the source.
# #
# Returns: nothing on success # Returns: - nothing on success
# If @device is not a valid block device, GenericError # - If @device is not a valid block device, GenericError
# #
# Since: 1.3 # Since: 1.3
# #
@ -2097,9 +2096,9 @@
# #
# Create a dirty bitmap with a name on the node, and start tracking the writes. # Create a dirty bitmap with a name on the node, and start tracking the writes.
# #
# Returns: nothing on success # Returns: - nothing on success
# If @node is not a valid block device or node, DeviceNotFound # - If @node is not a valid block device or node, DeviceNotFound
# If @name is already taken, GenericError with an explanation # - If @name is already taken, GenericError with an explanation
# #
# Since: 2.4 # Since: 2.4
# #
@ -2120,10 +2119,10 @@
# with block-dirty-bitmap-add. If the bitmap is persistent, remove it from its # with block-dirty-bitmap-add. If the bitmap is persistent, remove it from its
# storage too. # storage too.
# #
# Returns: nothing on success # Returns: - nothing on success
# If @node is not a valid block device or node, DeviceNotFound # - If @node is not a valid block device or node, DeviceNotFound
# If @name is not found, GenericError with an explanation # - If @name is not found, GenericError with an explanation
# if @name is frozen by an operation, GenericError # - if @name is frozen by an operation, GenericError
# #
# Since: 2.4 # Since: 2.4
# #
@ -2144,9 +2143,9 @@
# backup from this point in time forward will only backup clusters # backup from this point in time forward will only backup clusters
# modified after this clear operation. # modified after this clear operation.
# #
# Returns: nothing on success # Returns: - nothing on success
# If @node is not a valid block device, DeviceNotFound # - If @node is not a valid block device, DeviceNotFound
# If @name is not found, GenericError with an explanation # - If @name is not found, GenericError with an explanation
# #
# Since: 2.4 # Since: 2.4
# #
@ -2165,9 +2164,9 @@
# #
# Enables a dirty bitmap so that it will begin tracking disk changes. # Enables a dirty bitmap so that it will begin tracking disk changes.
# #
# Returns: nothing on success # Returns: - nothing on success
# If @node is not a valid block device, DeviceNotFound # - If @node is not a valid block device, DeviceNotFound
# If @name is not found, GenericError with an explanation # - If @name is not found, GenericError with an explanation
# #
# Since: 4.0 # Since: 4.0
# #
@ -2186,9 +2185,9 @@
# #
# Disables a dirty bitmap so that it will stop tracking disk changes. # Disables a dirty bitmap so that it will stop tracking disk changes.
# #
# Returns: nothing on success # Returns: - nothing on success
# If @node is not a valid block device, DeviceNotFound # - If @node is not a valid block device, DeviceNotFound
# If @name is not found, GenericError with an explanation # - If @name is not found, GenericError with an explanation
# #
# Since: 4.0 # Since: 4.0
# #
@ -2215,11 +2214,11 @@
# of the source bitmaps. This can be used to achieve backup checkpoints, or in # of the source bitmaps. This can be used to achieve backup checkpoints, or in
# simpler usages, to copy bitmaps. # simpler usages, to copy bitmaps.
# #
# Returns: nothing on success # Returns: - nothing on success
# If @node is not a valid block device, DeviceNotFound # - If @node is not a valid block device, DeviceNotFound
# If any bitmap in @bitmaps or @target is not found, GenericError # - If any bitmap in @bitmaps or @target is not found, GenericError
# If any of the bitmaps have different sizes or granularities, # - If any of the bitmaps have different sizes or granularities,
# GenericError # GenericError
# #
# Since: 4.0 # Since: 4.0
# #
@ -2251,10 +2250,10 @@
# #
# Get bitmap SHA256. # Get bitmap SHA256.
# #
# Returns: BlockDirtyBitmapSha256 on success # Returns: - BlockDirtyBitmapSha256 on success
# If @node is not a valid block device, DeviceNotFound # - If @node is not a valid block device, DeviceNotFound
# If @name is not found or if hashing has failed, GenericError with an # - If @name is not found or if hashing has failed, GenericError with an
# explanation # explanation
# #
# Since: 2.10 # Since: 2.10
## ##
@ -2371,8 +2370,8 @@
# the device will be removed from its group and the rest of its # the device will be removed from its group and the rest of its
# members will not be affected. The 'group' parameter is ignored. # members will not be affected. The 'group' parameter is ignored.
# #
# Returns: Nothing on success # Returns: - Nothing on success
# If @device is not a valid block device, DeviceNotFound # - If @device is not a valid block device, DeviceNotFound
# #
# Since: 1.1 # Since: 1.1
# #
@ -2622,7 +2621,8 @@
# list without user intervention. # list without user intervention.
# Defaults to true. (Since 3.1) # 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 # Since: 1.1
# #
@ -2656,8 +2656,8 @@
# @speed: the maximum speed, in bytes per second, or 0 for unlimited. # @speed: the maximum speed, in bytes per second, or 0 for unlimited.
# Defaults to 0. # Defaults to 0.
# #
# Returns: Nothing on success # Returns: - Nothing on success
# If no background operation is active on this device, DeviceNotActive # - If no background operation is active on this device, DeviceNotActive
# #
# Since: 1.1 # Since: 1.1
## ##
@ -2696,8 +2696,8 @@
# abandon the job immediately (even if it is paused) instead of waiting # abandon the job immediately (even if it is paused) instead of waiting
# for the destination to complete its final synchronization (since 1.3) # for the destination to complete its final synchronization (since 1.3)
# #
# Returns: Nothing on success # Returns: - Nothing on success
# If no background operation is active on this device, DeviceNotActive # - If no background operation is active on this device, DeviceNotActive
# #
# Since: 1.1 # Since: 1.1
## ##
@ -2720,8 +2720,8 @@
# the name of the parameter), but since QEMU 2.7 it can have # the name of the parameter), but since QEMU 2.7 it can have
# other values. # other values.
# #
# Returns: Nothing on success # Returns: - Nothing on success
# If no background operation is active on this device, DeviceNotActive # - If no background operation is active on this device, DeviceNotActive
# #
# Since: 1.3 # Since: 1.3
## ##
@ -2742,8 +2742,8 @@
# the name of the parameter), but since QEMU 2.7 it can have # the name of the parameter), but since QEMU 2.7 it can have
# other values. # other values.
# #
# Returns: Nothing on success # Returns: - Nothing on success
# If no background operation is active on this device, DeviceNotActive # - If no background operation is active on this device, DeviceNotActive
# #
# Since: 1.3 # Since: 1.3
## ##
@ -2770,8 +2770,8 @@
# the name of the parameter), but since QEMU 2.7 it can have # the name of the parameter), but since QEMU 2.7 it can have
# other values. # other values.
# #
# Returns: Nothing on success # Returns: - Nothing on success
# If no background operation is active on this device, DeviceNotActive # - If no background operation is active on this device, DeviceNotActive
# #
# Since: 1.3 # Since: 1.3
## ##

33
qapi/block.json
View File

@ -115,15 +115,12 @@
# #
# For the arguments, see the documentation of BlockdevSnapshotInternal. # For the arguments, see the documentation of BlockdevSnapshotInternal.
# #
# Returns: nothing on success # Returns: - nothing on success
# # - If @device is not a valid block device, GenericError
# If @device is not a valid block device, GenericError # - If any snapshot matching @name exists, or @name is empty,
# # GenericError
# If any snapshot matching @name exists, or @name is empty, # - If the format of the image used does not support it,
# GenericError # BlockFormatFeatureNotSupported
#
# If the format of the image used does not support it,
# BlockFormatFeatureNotSupported
# #
# Since: 1.7 # Since: 1.7
# #
@ -154,12 +151,12 @@
# #
# @name: optional the snapshot's name to be deleted # @name: optional the snapshot's name to be deleted
# #
# Returns: SnapshotInfo on success # Returns: - SnapshotInfo on success
# If @device is not a valid block device, GenericError # - If @device is not a valid block device, GenericError
# If snapshot not found, GenericError # - If snapshot not found, GenericError
# If the format of the image used does not support it, # - If the format of the image used does not support it,
# BlockFormatFeatureNotSupported # BlockFormatFeatureNotSupported
# If @id and @name are both not specified, GenericError # - If @id and @name are both not specified, GenericError
# #
# Since: 1.7 # Since: 1.7
# #
@ -197,10 +194,8 @@
# @force: If true, eject regardless of whether the drive is locked. # @force: If true, eject regardless of whether the drive is locked.
# If not specified, the default value is false. # If not specified, the default value is false.
# #
# Returns: Nothing on success # Returns: - Nothing on success
# # - If @device is not a valid block device, DeviceNotFound
# If @device is not a valid block device, DeviceNotFound
#
# Notes: Ejecting a device with no media results in success # Notes: Ejecting a device with no media results in success
# #
# Since: 0.14.0 # Since: 0.14.0

36
qapi/misc.json
View File

@ -430,12 +430,10 @@
# #
# Return information about the balloon device. # Return information about the balloon device.
# #
# Returns: @BalloonInfo on success # Returns: - @BalloonInfo on success
# # - If the balloon driver is enabled but not functional because the KVM
# If the balloon driver is enabled but not functional because the KVM # kernel module cannot support it, KvmMissingCap
# kernel module cannot support it, KvmMissingCap # - If no balloon device is present, DeviceNotActive
#
# If no balloon device is present, DeviceNotActive
# #
# Since: 0.14.0 # Since: 0.14.0
# #
@ -492,8 +490,8 @@
# #
# @bar: the index of the Base Address Register for this region # @bar: the index of the Base Address Register for this region
# #
# @type: 'io' if the region is a PIO region # @type: - 'io' if the region is a PIO region
# 'memory' if the region is a MMIO region # - 'memory' if the region is a MMIO region
# #
# @size: memory size # @size: memory size
# #
@ -1004,10 +1002,10 @@
# #
# @value: the target size of the balloon in bytes # @value: the target size of the balloon in bytes
# #
# Returns: Nothing on success # Returns: - Nothing on success
# If the balloon driver is enabled but not functional because the KVM # - If the balloon driver is enabled but not functional because the KVM
# kernel module cannot support it, KvmMissingCap # 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, # 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 # 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 # If @device is 'vnc' and @target is 'password', this is the new VNC
# password to set. See change-vnc-password for additional notes. # password to set. See change-vnc-password for additional notes.
# #
# Returns: Nothing on success. # Returns: - Nothing on success.
# If @device is not a valid block device, DeviceNotFound # - If @device is not a valid block device, DeviceNotFound
# #
# Notes: This interface is deprecated, and it is strongly recommended that you # Notes: This interface is deprecated, and it is strongly recommended that you
# avoid using it. For changing block devices, use # 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. # @opaque: A free-form string that can be used to describe the fd.
# #
# Returns: @AddfdInfo on success # Returns: - @AddfdInfo on success
# # - If file descriptor was not received, FdNotSupplied
# If file descriptor was not received, FdNotSupplied # - If @fdset-id is a negative value, InvalidParameterValue
#
# If @fdset-id is a negative value, InvalidParameterValue
# #
# Notes: The list of fd sets is shared by all monitor connections. # 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. # @fd: The file descriptor that is to be removed.
# #
# Returns: Nothing on success # Returns: - Nothing on success
# If @fdset-id or @fd is not found, FdNotFound # - If @fdset-id or @fd is not found, FdNotFound
# #
# Since: 1.2.0 # Since: 1.2.0
# #

4
qapi/tpm.json
View File

@ -96,8 +96,8 @@
# #
# A union referencing different TPM backend types' configuration options # A union referencing different TPM backend types' configuration options
# #
# @type: 'passthrough' The configuration options for the TPM passthrough type # @type: - 'passthrough' The configuration options for the TPM passthrough type
# 'emulator' The configuration options for TPM emulator backend type # - 'emulator' The configuration options for TPM emulator backend type
# #
# Since: 1.5 # Since: 1.5
## ##

63
qapi/ui.json
View File

@ -12,8 +12,8 @@
# #
# Sets the password of a remote display session. # Sets the password of a remote display session.
# #
# @protocol: 'vnc' to modify the VNC server password # @protocol: - 'vnc' to modify the VNC server password
# 'spice' to modify the Spice server password # - 'spice' to modify the Spice server password
# #
# @password: the new password # @password: the new password
# #
@ -23,8 +23,8 @@
# 'disconnect' to disconnect existing clients # 'disconnect' to disconnect existing clients
# 'keep' to maintain existing clients # 'keep' to maintain existing clients
# #
# Returns: Nothing on success # Returns: - Nothing on success
# If Spice is not enabled, DeviceNotFound # - If Spice is not enabled, DeviceNotFound
# #
# Since: 0.14.0 # Since: 0.14.0
# #
@ -46,13 +46,14 @@
# @protocol: the name of the remote display protocol 'vnc' or 'spice' # @protocol: the name of the remote display protocol 'vnc' or 'spice'
# #
# @time: when to expire the password. # @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 # - 'now' to expire the password immediately
# If @protocol is 'spice' and Spice is not active, DeviceNotFound # - '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 # Since: 0.14.0
# #
@ -201,9 +202,10 @@
# @tls-port: The SPICE server's TLS port number. # @tls-port: The SPICE server's TLS port number.
# #
# @auth: the current authentication type used by the server # @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 # - 'none' if no authentication is being used
# line options # - '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 # @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 # 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 # @host: The hostname the VNC server is bound to. This depends on
# the name resolution on the host and may be an IP address. # the name resolution on the host and may be an IP address.
# #
# @family: 'ipv6' if the host is listening for IPv6 connections # @family: - 'ipv6' if the host is listening for IPv6 connections
# 'ipv4' if the host is listening for IPv4 connections # - 'ipv4' if the host is listening for IPv4 connections
# 'unix' if the host is listening on a unix domain socket # - 'unix' if the host is listening on a unix domain socket
# 'unknown' otherwise # - 'unknown' otherwise
# #
# @service: The service name of the server's port. This may depends # @service: The service name of the server's port. This may depends
# on the host system's service database so symbolic names should not # on the host system's service database so symbolic names should not
# be relied on. # be relied on.
# #
# @auth: the current authentication type used by the server # @auth: the current authentication type used by the server
# 'none' if no authentication is being used #
# 'vnc' if VNC authentication is being used # - 'none' if no authentication is being used
# 'vencrypt+plain' if VEncrypt is used with plain text authentication # - 'vnc' if VNC authentication is being used
# 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication # - 'vencrypt+plain' if VEncrypt is used with plain text authentication
# 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication # - 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication
# 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth # - 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication
# 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth # - 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth
# 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth # - 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
# 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth # - 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
# 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth # - 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth
# 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL 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 # @clients: a list of @VncClientInfo of all currently connected clients
# #
@ -840,8 +843,8 @@
# @hold-time: time to delay key up events, milliseconds. Defaults # @hold-time: time to delay key up events, milliseconds. Defaults
# to 100 # to 100
# #
# Returns: Nothing on success # Returns: - Nothing on success
# If key is unknown or redundant, InvalidParameter # - If key is unknown or redundant, InvalidParameter
# #
# Since: 1.3.0 # Since: 1.3.0
# #