| Message ID | 20230428105429.1687850-11-armbru@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | qapi: Reformat doc comments | expand |
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?
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!
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.
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 445471daee..34c3dcbe97 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -54,7 +54,7 @@ ## # @Enum: # -# @one: The _one_ {and only} +# @one: The _one_ {and only}, description on the same line # # Features: # @enum-feat: Also _one_ {and only} @@ -73,7 +73,8 @@ # @Base: # # @base1: -# the first member +# description starts on a new line, +# not indented ## { 'struct': 'Base', 'data': { 'base1': 'Enum' }, 'if': { 'all': ['IFALL1', 'IFALL2'] } } @@ -120,7 +121,8 @@ ## # @Alternate: # -# @i: an integer +# @i: description starts on the same line +# remainder indented the same # @b is undocumented # # Features: @@ -138,10 +140,11 @@ ## # @cmd: # -# @arg1: the first argument +# @arg1: +# description starts on a new line, +# indented # -# @arg2: the second -# argument +# @arg2: the second argument # # Features: # @cmd-feat1: a feature diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index afa48dcd94..2ba72ae558 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -104,7 +104,7 @@ doc symbol=Enum body= arg=one -The _one_ {and only} +The _one_ {and only}, description on the same line arg=two feature=enum-feat @@ -117,12 +117,13 @@ doc symbol=Base body= arg=base1 -the first member +description starts on a new line, +not indented doc symbol=Variant1 body= A paragraph -Another paragraph (but no @var: line) +Another paragraph @var1 is undocumented arg=var1 @@ -143,7 +144,8 @@ doc symbol=Alternate body= arg=i -an integer +description starts on the same line +remainder indented the same @b is undocumented arg=b @@ -156,10 +158,10 @@ doc symbol=cmd body= arg=arg1 -the first argument +description starts on a new line, + indented arg=arg2 -the second -argument +the second argument arg=arg3 feature=cmd-feat1
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> --- tests/qapi-schema/doc-good.json | 15 +++++++++------ tests/qapi-schema/doc-good.out | 16 +++++++++------- 2 files changed, 18 insertions(+), 13 deletions(-)