On Tue, Sep 22, 2026 at 1:06 PM Markus Armbruster <[email protected]> wrote:
>
> John Snow <[email protected]> writes:
>
> > Signed-off-by: John Snow <[email protected]>
> > ---
> > tests/qapi-schema/doc-good.json | 10 +++++-----
> > tests/qapi-schema/doc-good.out | 13 +++++--------
> > tests/qapi-schema/doc-interleaved-section.err | 2 +-
> > tests/qapi-schema/doc-interleaved-section.json | 3 +--
> > 4 files changed, 12 insertions(+), 16 deletions(-)
> >
> > diff --git a/tests/qapi-schema/doc-good.json
> > b/tests/qapi-schema/doc-good.json
> > index fac13425b72..00721d5c522 100644
> > --- a/tests/qapi-schema/doc-good.json
> > +++ b/tests/qapi-schema/doc-good.json
> > @@ -94,12 +94,11 @@
> >
> > ##
> > # @Variant1:
> > +# A paragraph
> > #
> > -# A paragraph
> > +# Another paragraph
> > #
> > -# Another paragraph
> > -#
> > -# @var1 is undocumented
> > +# @var1 is undocumented
>
> Let's keep '@var1 is undocumented' plain. That way, it stays close to
> "author forgot the colon after the member name", which I find useful.
OK, but it will very soon be disallowed in that position; it will have
to be moved below Features et al, eventually. Making this change, but
heads up that it necessitates another patch in the order enforcement
series.
>
> > #
> > # Features:
> > # @variant1-feat: a feature
> > @@ -206,7 +205,8 @@
> >
> > ##
> > # @cmd-boxed:
> > -# If you're bored enough to read this, go see a video of boxed cats
> > +# If you're bored enough to read this, go see a video of boxed
> > +# cats
> > #
> > # Features:
> > # @cmd-feat1: a feature
> > diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
> > index 371dd25ffc7..8c0818a3f0d 100644
> > --- a/tests/qapi-schema/doc-good.out
> > +++ b/tests/qapi-schema/doc-good.out
> > @@ -126,13 +126,11 @@ doc symbol=Base
> > minimally indented
> > doc symbol=Variant1
> > Intro
> > + A paragraph
> >
> > - Plain
> > -A paragraph
> > + Another paragraph
> >
> > -Another paragraph
> > -
> > -@var1 is undocumented
> > + @var1 is undocumented
> > Member=var1
> >
> > Feature=variant1-feat
> > @@ -213,9 +211,8 @@ Note::
> > 2.10
> > doc symbol=cmd-boxed
> > Intro
> > -
> > - Plain
> > -If you're bored enough to read this, go see a video of boxed cats
> > + If you're bored enough to read this, go see a video of boxed
> > + cats
> > Feature=cmd-feat1
> > a feature
> > Feature=cmd-feat2
>
> I'm mildly surprised that the intro's indentation isn't stripped. Maybe
> we discussed that already, and I forgot. Anyway, it works, and changing
> it is way out of scope right now.
*searching resident databanks*
I think I was striving for minimal processing of the text prior to
handoff to sphinx for reasons of preserving accurate source
information.
qapidoc.py has this code:
```
def visit_plaintext(self, section: QAPIDoc.Section) -> None:
# Squelch empty paragraphs.
if not section.text:
return
# Intro sections, which are indented in QAPI source, need to
# be dedented to avoid accidental block quotes in ReST syntax.
dedent = bool(section.kind == QAPIDoc.Kind.INTRO)
self.ensure_blank_line()
self.add_lines(section.text, section.info, dedent)
self.ensure_blank_line()
```
As a result, the unit test plaintext versions retain that indentation.
This actually matches how we treat indentation for member text, which
is also preserved and represented in the plaintext test output!
Granted, now that I have excised the backwards compatibility demon
from qapidoc, it is possible we can conduct another audit on source
information preservation and some things might be able to be
simplified, but I think this is fine and good for now.
>
> > diff --git a/tests/qapi-schema/doc-interleaved-section.err
> > b/tests/qapi-schema/doc-interleaved-section.err
> > index e5d1ef54c1b..85f01fa57a7 100644
> > --- a/tests/qapi-schema/doc-interleaved-section.err
> > +++ b/tests/qapi-schema/doc-interleaved-section.err
> > @@ -1 +1 @@
> > -doc-interleaved-section.json:15:1: description of '@foobar:' follows a
> > section
> > +doc-interleaved-section.json:14:1: description of '@foobar:' follows a
> > section
> > diff --git a/tests/qapi-schema/doc-interleaved-section.json
> > b/tests/qapi-schema/doc-interleaved-section.json
> > index eec01ed5650..bc0937b8601 100644
> > --- a/tests/qapi-schema/doc-interleaved-section.json
> > +++ b/tests/qapi-schema/doc-interleaved-section.json
> > @@ -2,8 +2,7 @@
> >
> > ##
> > # @TestStruct:
> > -#
> > -# body
> > +# body
> > #
> > # @integer: foo
> > # blah
>
