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

[Juan Quintela]

Markus Armbruster <armbru@redhat.com> wrote:
> 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 for the explanation.