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 14:43, Markus Armbruster <armbru@redhat.com> wrote:
>
>
>> 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.
>
> Conveniently this patchset already supports this format :-)
> You can write either
>
> # @foo: bar
> #       baz
> #         indented
>
> or
> # @foo:
> # bar
> # baz
> #   indented
>
> and they'll come out to the same thing (the parser.py code
> sends the same doc strings to the rST visitor).

If we enforce the second format in the QAPI schema parser, we save
ourselves the trouble of normalizing the first format to the second one.
We also promote more uniform style.