Juan Quintela <[email protected]> writes:
> Markus Armbruster <[email protected]> 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 <[email protected]>
>
> Reviewed-by: Juan Quintela <[email protected]>
>
>> ##
>> # @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!
