Re: [PATCH 08/29] qapi: Use ':' after @argument in doc comments

[Markus Armbruster <armbru@redhat.com>]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Fri, 7 Feb 2020 at 10:24, Kevin Wolf <kwolf@redhat.com> wrote:
>>
>> Am 07.02.2020 um 10:28 hat Markus Armbruster geschrieben:
>> > Peter Maydell <peter.maydell@linaro.org> writes:
>> > > @@ -4703,7 +4703,7 @@
>> > >  #
>> > >  # Options for creating an image format on a given node.
>> > >  #
>> > > -# @driver           block driver to create the image format
>> > > +# @driver: block driver to create the image format
>> > >  #
>> > >  # Since: 2.12
>> > >  ##
>> >
>> > Loses the visual alignment.  I'm okay with that, but the folks who took
>> > the trouble to align the text may have different ideas.  Cc'ing Kevin
>> > and Max.
>>
>> I think the documentation is much easier to parse visually with aligned
>> text as it makes both the option name and the whole part of the comment
>> that documents options stand out clearly.
>>
>> Of course, "It is the QEMU coding style." would trump everything, but as
>> long as there isn't a style guide that requires a wall of text without
>> spaces and alignment, I'd prefer to leave at least those aligned texts
>> in place that we have.
>
> So, the other way to handle this would be to say "the @foo: can have
> an arbitrary amount of whitespace after it", and have the doc comment
> parser strip out that many characters of extra whitespace there and
> on the subsequent lines. The downside is that then you would have no
> way of having a comment for an argument which started with rST markup
> that required leading whitespace. I think this pretty much would just
> mean that you can't start an argument description with a blockquote,
> so we don't lose much, but there is a difference currently between:
>
> @arg:    In the current parser this is a blockquote
>          Blockquote line 2
>
>       But this is a non-blockquoted line still in @arg's description
>
> and
>
> @arg: This is not blockquoted, it's just a line
>       So is this
>       and this
>
> I can make the parser work the other way if people prefer that though
> (and then the first example above would become a syntax error because
> the 3rd line would be unexpectedly de-indented).

Let me ignore rST details for a bit.

The prevailing schema style looks like this:

    # @file: Node to create the image format on
    # @size: Size of the virtual disk in bytes
    # @log-size: Log size in bytes, must be a multiple of 1 MB
    #            (default: 1 MB)
    # @block-size: Block size in bytes, must be a multiple of 1 MB and not
    #              larger than 256 MB (default: automatically choose a block
    #              size depending on the image size)
    # @subformat: vhdx subformat (default: dynamic)
    # @block-state-zero: Force use of payload blocks of type 'ZERO'. Non-standard,
    #                    but default.  Do not set to 'off' when using 'qemu-img
    #                    convert' with subformat=dynamic.

Peter's patch converts to it.  Can't fault him for converting to the
prevailing style.

Trouble is the prevailing style is ugly, and can waste massive amounts
of screen real estate when both the identifier and the explaining text
are long.

block*.json's style looks like this:

    # @file:             Node to create the image format on
    # @size:             Size of the virtual disk in bytes
    # @log-size:         Log size in bytes, must be a multiple of 1 MB
    #                    (default: 1 MB)
    # @block-size:       Block size in bytes, must be a multiple of 1 MB and not
    #                    larger than 256 MB (default: automatically choose a block
    #                    size depending on the image size)
    # @subformat:        vhdx subformat (default: dynamic)
    # @block-state-zero: Force use of payload blocks of type 'ZERO'. Non-standard,
    #                    but default.  Do not set to 'off' when using 'qemu-img
    #                    convert' with subformat=dynamic.

I dislike this style, too.  It's less ugly, until you add a longer
member.  Then you either accept inconsistent indentation, or reindent
all the other members.  Blech.

Here's a style I'd dislike less:

    # @file: Node to create the image format on
    #
    # @size: Size of the virtual disk in bytes
    #
    # @log-size: Log size in bytes, must be a multiple of 1 MB
    #     (default: 1 MB)
    #
    # @block-size: Block size in bytes, must be a multiple of 1 MB and not
    #     larger than 256 MB (default: automatically choose a block
    #     size depending on the image size)
    #
    # @subformat: vhdx subformat (default: dynamic)
    #
    # @block-state-zero: Force use of payload blocks of type 'ZERO'.
    #     Non-standard, but default.  Do not set to 'off' when using
    #     'qemu-img convert' with subformat=dynamic.

Or maybe even

    # @file:
    # Node to create the image format on
    #
    # @size:
    # Size of the virtual disk in bytes
    #
    # @log-size:
    # Log size in bytes, must be a multiple of 1 MB (default: 1 MB)
    #
    # @block-size:
    # Block size in bytes, must be a multiple of 1 MB and not larger
    # than 256 MB (default: automatically choose a block size depending
    # on the image size)
    #
    # @subformat:
    # vhdx subformat (default: dynamic)
    #
    # @block-state-zero:
    # Force use of payload blocks of type 'ZERO'.  Non-standard, but
    # default.  Do not set to 'off' when using 'qemu-img convert' with
    # subformat=dynamic.

With both these styles, member names stand out reasonably well, and I
don't have to fiddle with indentation when adding or removing members.
With the second one, I don't have to fiddle with indentation at all.

The second one might be the better fit for rST, but that's for Peter to
judge.