On 2/6/20 6:30 PM, Peter Maydell wrote:
> 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 in the HTML and manpage 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.
>
> This commit gathers up the remaining json files which had
> places needing this fix.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> qapi/block.json | 33 ++++++++++++++-------------------
> qapi/misc.json | 36 ++++++++++++++++--------------------
> qapi/tpm.json | 4 ++--
> 3 files changed, 32 insertions(+), 41 deletions(-)
>
> diff --git a/qapi/block.json b/qapi/block.json
> index 905297bab2e..e509cc53506 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 626a342b008..06c80b58a24 100644
> --- a/qapi/misc.json
> +++ b/qapi/misc.json
> @@ -418,12 +418,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
> #
> @@ -480,8 +478,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
> #
> @@ -992,10 +990,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
> @@ -1074,8 +1072,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
> @@ -1225,11 +1223,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.
> #
> @@ -1257,8 +1253,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 63878aa0f47..dc1f0817399 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
> ##
>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>