Re: [PATCH 6/7] qapi: Drop unnecessary horizontal spacing in comments

[Markus Armbruster]

Andrea Bolognani <abologna@redhat.com> writes:

> Care was taken not to break vertical alignment.
>
> Signed-off-by: Andrea Bolognani <abologna@redhat.com>
> ---
>  qapi/block-core.json   | 62 +++++++++++++++++++++---------------------
>  qapi/block-export.json |  2 +-
>  qapi/block.json        |  2 +-
>  qapi/char.json         |  2 +-
>  qapi/control.json      | 10 +++----
>  qapi/crypto.json       | 44 +++++++++++++++---------------
>  qapi/dump.json         |  4 +--
>  qapi/machine.json      |  8 +++---
>  qapi/misc-target.json  |  6 ++--
>  qapi/misc.json         |  6 ++--
>  qapi/run-state.json    |  4 +--
>  qapi/sockets.json      |  6 ++--
>  qapi/ui.json           | 18 ++++++------
>  13 files changed, 87 insertions(+), 87 deletions(-)
>
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index 2bce5bb0ae..5fd66ea676 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -337,9 +337,9 @@
>  #
>  # Cache mode information for a block device
>  #
> -# @writeback:   true if writeback mode is enabled
> -# @direct:      true if the host page cache is bypassed (O_DIRECT)
> -# @no-flush:    true if flush requests are ignored for the device
> +# @writeback: true if writeback mode is enabled
> +# @direct:    true if the host page cache is bypassed (O_DIRECT)
> +# @no-flush:  true if flush requests are ignored for the device

I'm no fan of horizontally aligning descriptions, because when you add a
longer name, you either realign (I hate the churn) or live with the
inconsistency (I hate that, too).

For what it's worth, the example in docs/devel/qapi-code-gen.rst does
not align.

I doubt changing to a different alignment now is useful.  The next
patch, however, drops the alignment entirely.  Possibly useful.

Thoughts?

>  #
>  # Since: 2.3
>  ##
> @@ -604,7 +604,7 @@
>  # @inserted: @BlockDeviceInfo describing the device if media is
>  #            present
>  #
> -# Since:  0.14
> +# Since: 0.14

This one is TAG: TEXT, whereas the one above is a multiple @NAME:
DESCRIPTION.  Extra space in the latter can provide alignment.  Extra
space in the former is always redundant.  I'd take a patch dropping
these obviously redundant spaces without debate :)

[...]