Re: [PATCH 13/17] qapi: Relax doc string @name: description indentation rules

[Markus Armbruster]

Juan Quintela <quintela@redhat.com> writes:

> Markus Armbruster <armbru@redhat.com> wrote:
>> The QAPI schema doc comment language provides special syntax for
>> command and event arguments, struct and union members, alternate
>> branches, enumeration values, and features: descriptions starting with
>> "@name:".
>>
>> By convention, we format them like this:
>>
>>     # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit,
>>     #        sed do eiusmod tempor incididunt ut labore et dolore
>>     #        magna aliqua.
>>
>> Okay for names as short as "name", but we have much longer ones.  Their
>> description gets squeezed against the right margin, like this:
>>
>>     # @dirty-sync-missed-zero-copy: Number of times dirty RAM 
>> synchronization could
>>     #                               not avoid copying dirty pages. This is 
>> between
>>     #                               0 and @dirty-sync-count * 
>> @multifd-channels.
>>     #                               (since 7.1)
>>
>> The description text is effectively just 50 characters wide.  Easy
>> enough to read, but can be cumbersome to write.
>>
>> The awkward squeeze against the right margin makes people go beyond it,
>> which produces two undesirables: arguments about style, and descriptions
>> that are unnecessarily hard to read, like this one:
>>
>>     # @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU.  
>> This is
>>     #                           only present when the postcopy-blocktime 
>> migration capability
>>     #                           is enabled. (Since 3.0)
>>
>> We could instead format it like
>>
>>     # @postcopy-vcpu-blocktime:
>>     # list of the postcopy blocktime per vCPU.  This is only present
>>     # when the postcopy-blocktime migration capability is
>>     # enabled. (Since 3.0)
>>
>> or, since the commit before previous, like
>>
>>     # @postcopy-vcpu-blocktime:
>>     #          list of the postcopy blocktime per vCPU.  This is only present
>>     #          when the postcopy-blocktime migration capability is
>>     #          enabled. (Since 3.0)
>>
>> However, I'd rather have
>>
>>     # @postcopy-vcpu-blocktime: list of the postcopy blocktime per vCPU.
>>     #     This is only present when the postcopy-blocktime migration
>>     #     capability is enabled.  (Since 3.0)
>>
>> because this is how rST field and option lists work.
>>
>> To get this, we need to let the first non-blank line after the
>> "@name:" line determine expected indentation.
>>
>> This fills up the indentation pitfall mentioned in
>> docs/devel/qapi-code-gen.rst.  A related pitfall still exists.  Update
>> the text to show it.
>>
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>
> Reviewed-by: Juan Quintela <quintela@redhat.com>
>
>> ---
>>  docs/devel/qapi-code-gen.rst          | 10 ++--
>>  scripts/qapi/parser.py                | 73 +++++++--------------------
>>  tests/qapi-schema/doc-bad-indent.err  |  2 +-
>>  tests/qapi-schema/doc-bad-indent.json |  3 +-
>
> bad order of files
>
>>  tests/qapi-schema/doc-good.json       |  3 +-
>>  tests/qapi-schema/doc-good.out        |  3 +-
>
> good order of files
>
> Should we tweak orderfiles so it displays first the json, and the err or
> out files. reviewing json and then output makes things (at least to me)
> simpler.

I'll look into it.

Thanks!