Re: [PATCH 10/17] tests/qapi-schema/doc-good: Improve argument description tests

[Markus Armbruster]

Juan Quintela <quintela@redhat.com> writes:

> Markus Armbruster <armbru@redhat.com> wrote:
>> Improve the comments to better describe what they test.
>>
>> Cover argument description starting on a new line indented.  This
>> style isn't documented in docs/devel/qapi-code-gen.rst.  qapi-gen.py
>> accepts it, but messes up indentation: it's stripped from the first
>> line, not subsequent ones.  The next commit will fix this.
>>
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>
> Reviewed-by: Juan Quintela <quintela@redhat.com>
>
>>  ##
>>  # @Alternate:
>>  #
>> -# @i: an integer
>> +# @i: description starts on the same line
>> +#     remainder indented the same
>>  #     @b is undocumented
>>  #
>>  # Features:
>
> Just curious, what is trying to convey this
>    @b is undocumented
> At the same indentation that the description of @i?

Writing it like

    # @i: description starts on the same line
    #     remainder indented the same
    # @b is undocumented
    #
    # Features:
    # @alt-feat: a feature

fails with "unexpected de-indent (expected at least 4 spaces)".  That's
because the @b line is part of the argument section @i, and the doc
parser insists its indented consistently.  Guards against some editing
accidents, like forgetting the ':'.

Writing it like

    # @i: description starts on the same line
    #     remainder indented the same
    #
    # @b is undocumented
    #
    # Features:
    # @alt-feat: a feature

fails with "'@alt-feat:' can't follow 'None' section".  That's because
the @b line is now a section of its own, and the doc parser requires
sections to be in a certain order.  Similar guard against editing
accidents.  Not foolproof; it only works here because a feature section
follows.  If we wanted sane syntax, we would've stuck to TexInfo.

The error message is bad; I'll improve it.

Thanks!