Markus Armbruster <arm...@redhat.com> wrote: > Juan Quintela <quint...@redhat.com> writes: > >> Markus Armbruster <arm...@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 <arm...@redhat.com> >> >> Reviewed-by: Juan Quintela <quint...@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.
