Re: [PATCH v4 5/7] qapi/parser: fix intermediate "intro" detection

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> On Thu, Sep 17, 2026 at 1:13 AM Markus Armbruster <armbru@redhat.com> wrote:
>>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > In 43e7ad1a3fa5, I adjusted the insertion algorithm for inserting
>> > something after the "introduction" to cope with both the old and new
>> > syntax while we converted QAPI to the new syntax. There's a bug in
>> > that code that only shows up in a handful of cases and only when using
>> > the new syntax while this affordance/flex code is still enabled.
>> >
>> > In the case that we do actually have a real bona-fide intro section,
>> > we want to insert directly after that real-deal intro section, not
>> > after any plaintext sections that may follow it. This code adjusts the
>> > temporary code to strongly prefer inserting after the actual intro
>> > section if it exists.
>> >
>> > Once again: once conversion is done, you will be delighted by how much
>> > of this ugly code goes away.
>> >
>> > Signed-off-by: John Snow <jsnow@redhat.com>
>> > ---
>> >  scripts/qapi/parser.py | 8 ++++++++
>> >  1 file changed, 8 insertions(+)
>> >
>> > diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
>> > index 9e14c2f7921..6a9a5589c14 100644
>> > --- a/scripts/qapi/parser.py
>> > +++ b/scripts/qapi/parser.py
>> > @@ -845,6 +845,14 @@ def _insert_after_intro(
>> >          needed and ``_insert_near_kind(QAPIDoc.Kind.INTRO, ...)`` will
>> >          be sufficient.
>> >          """
>> > +        first = self.all_sections[0]
>> > +        if first.text and first.kind == QAPIDoc.Kind.INTRO:
>> > +            # First section is introduction and is non-empty: insert here.
>> > +            # Rest assured all of this ugliness will very soon go away.
>> > +            # Pinkie-swear.
>> > +            self._insert_near_kind(QAPIDoc.Kind.INTRO, section, after=True)
>>
>> Isn't this a roundabout way to do
>>
>>                self.all_sections.insert(1, section)
>>
>> ?
>
> Yes O:-)
>
> ... but it's the more semantically abstracted version that does not
> rely on the specific location of the section. By the end of the
> next-next series, all of this goes away anyway. I think I was
> preferring to avoid using insert in more than the two helpers we
> already use it in. (But since I intend to delete it all, I don't
> really care about fighting for purity in isolating this call.)
>
> Specifically:
>
> _insert_near_kind(), _insert_after_intro() both go away.
> append_member_stub() also goes away. ensure_returns() stays but
> becomes something like two lines.
>
> *all* section modification in the next-next series happens exclusively
> through a method named `_append()` which Does The Right Thing In All
> Cases.
>
> --js

What caught my eye was the dissonance between self._insert_near_kind()
above and self.all_sections.insert() below.

Then I looked at ._insert_near_kind().  It inserts before or after the
last section of a certain kind.  Here, it inserts after the last INTRO.
Since we always have exactly INTRO, and it always comes first, it
inserts after the first section.  Just what the comment says.  Good.
But why not just do what the comment says in the most straightforward
way possible?  Am I missing something?  Thus my question.

>>
>> > +            return
>> > +
>> >          index = 0
>> >          for index, ref_section in enumerate(self.all_sections):
>> >              if ref_section.kind.name in ("PLAIN", "INTRO"):
>>                    continue
>>                break
>>            else:
>>                index += 1
>>
>>            self.all_sections.insert(index, section)
>>