Re: [PATCH 17/17] qapi: Reformat doc comments to conform to current conventions

[Lukas Straub]

On Fri, 28 Apr 2023 12:54:29 +0200
Markus Armbruster <armbru@redhat.com> wrote:

> Change
> 
>     # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
>     #        do eiusmod tempor incididunt ut labore et dolore magna aliqua.
> 
> to
> 
>     # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
>     #     do eiusmod tempor incididunt ut labore et dolore magna aliqua.
> 
> See recent commit "qapi: Relax doc string @name: description
> indentation rules" for rationale.
> 
> Reflow paragraphs to 70 columns width, and consistently use two spaces
> to separate sentences.
> 
> To check the generated documentation does not change, I compared the
> generated HTML before and after this commit with "wdiff -3".  Finds no
> differences.  Comparing with diff is not useful, as the reflown
> paragraphs are visible there.
> 
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Acked-by: Lukas Straub <lukasstraub2@web.de>

> ---
>  qapi/acpi.json           |   50 +-
>  qapi/audio.json          |   85 +-
>  qapi/authz.json          |   29 +-
>  qapi/block-core.json     | 2801 ++++++++++++++++++++------------------
>  qapi/block-export.json   |  242 ++--
>  qapi/block.json          |  214 +--
>  qapi/char.json           |  134 +-
>  qapi/common.json         |   19 +-
>  qapi/compat.json         |   13 +-
>  qapi/control.json        |   59 +-
>  qapi/crypto.json         |  261 ++--
>  qapi/cryptodev.json      |    3 +
>  qapi/cxl.json            |   74 +-
>  qapi/dump.json           |   78 +-
>  qapi/error.json          |    6 +-
>  qapi/introspect.json     |   89 +-
>  qapi/job.json            |  139 +-
>  qapi/machine-target.json |  303 +++--
>  qapi/machine.json        |  389 +++---
>  qapi/migration.json      | 1117 ++++++++-------
>  qapi/misc-target.json    |   67 +-
>  qapi/misc.json           |  180 ++-
>  qapi/net.json            |  260 ++--
>  qapi/pci.json            |   35 +-
>  qapi/qapi-schema.json    |   25 +-
>  qapi/qdev.json           |   63 +-
>  qapi/qom.json            |  404 +++---
>  qapi/rdma.json           |    1 -
>  qapi/replay.json         |   48 +-
>  qapi/rocker.json         |   20 +-
>  qapi/run-state.json      |  215 +--
>  qapi/sockets.json        |   50 +-
>  qapi/stats.json          |   83 +-
>  qapi/tpm.json            |   20 +-
>  qapi/trace.json          |   34 +-
>  qapi/transaction.json    |   87 +-
>  qapi/ui.json             |  435 +++---
>  qapi/virtio.json         |   84 +-
>  qapi/yank.json           |   42 +-
>  39 files changed, 4322 insertions(+), 3936 deletions(-)
> 
> [...]
> 
> diff --git a/qapi/yank.json b/qapi/yank.json
> index 1639744ada..87ec7cab96 100644
> --- a/qapi/yank.json
> +++ b/qapi/yank.json
> @@ -9,7 +9,7 @@
>  ##
>  # @YankInstanceType:
>  #
> -# An enumeration of yank instance types. See @YankInstance for more
> +# An enumeration of yank instance types.  See @YankInstance for more
>  # information.
>  #
>  # Since: 6.0
> @@ -20,8 +20,8 @@
>  ##
>  # @YankInstanceBlockNode:
>  #
> -# Specifies which block graph node to yank. See @YankInstance for more
> -# information.
> +# Specifies which block graph node to yank.  See @YankInstance for
> +# more information.
>  #
>  # @node-name: the name of the block graph node
>  #
> @@ -33,8 +33,8 @@
>  ##
>  # @YankInstanceChardev:
>  #
> -# Specifies which character device to yank. See @YankInstance for more
> -# information.
> +# Specifies which character device to yank.  See @YankInstance for
> +# more information.
>  #
>  # @id: the chardev's ID
>  #
> @@ -46,21 +46,18 @@
>  ##
>  # @YankInstance:
>  #
> -# A yank instance can be yanked with the @yank qmp command to recover from a
> -# hanging QEMU.
> +# A yank instance can be yanked with the @yank qmp command to recover
> +# from a hanging QEMU.
>  #
>  # Currently implemented yank instances:
>  #
> -# - nbd block device:
> -#   Yanking it will shut down the connection to the nbd server without
> -#   attempting to reconnect.
> -# - socket chardev:
> -#   Yanking it will shut down the connected socket.
> -# - migration:
> -#   Yanking it will shut down all migration connections. Unlike
> -#   @migrate_cancel, it will not notify the migration process, so migration
> -#   will go into @failed state, instead of @cancelled state. @yank should be
> -#   used to recover from hangs.
> +# - nbd block device: Yanking it will shut down the connection to the
> +#   nbd server without attempting to reconnect.
> +# - socket chardev: Yanking it will shut down the connected socket.
> +# - migration: Yanking it will shut down all migration connections.
> +#   Unlike @migrate_cancel, it will not notify the migration process,
> +#   so migration will go into @failed state, instead of @cancelled
> +#   state.  @yank should be used to recover from hangs.
>  #
>  # Since: 6.0
>  ##
> @@ -74,13 +71,14 @@
>  ##
>  # @yank:
>  #
> -# Try to recover from hanging QEMU by yanking the specified instances. See
> -# @YankInstance for more information.
> +# Try to recover from hanging QEMU by yanking the specified instances.
> +# See @YankInstance for more information.
>  #
>  # Takes a list of @YankInstance as argument.
>  #
> -# Returns: - Nothing on success
> -#          - @DeviceNotFound error, if any of the YankInstances doesn't exist
> +# Returns:
> +# - Nothing on success
> +# - @DeviceNotFound error, if any of the YankInstances doesn't exist
>  #
>  # Example:
>  #
> @@ -101,7 +99,7 @@
>  ##
>  # @query-yank:
>  #
> -# Query yank instances. See @YankInstance for more information.
> +# Query yank instances.  See @YankInstance for more information.
>  #
>  # Returns: list of @YankInstance
>  #



--

pgp6r9CfQN32x.pgp
Description: OpenPGP digital signature