Re: [PATCH 16/29] qapi/{block, misc, tmp}.json: Use explicit bulleted lists

["Philippe Mathieu-Daudé" <philmd@redhat.com>]

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>