Re: [PATCH 09/14] qapi/parser: remove _insert_after_intro() helper

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> On Tue, Sep 29, 2026, 9:09 AM Markus Armbruster <armbru@redhat.com> wrote:
>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > I promised I'd remove this.
>> >
>> > Signed-off-by: John Snow <jsnow@redhat.com>
>> > ---
>> >  scripts/qapi/parser.py | 49 ++++++------------------------------------
>> >  1 file changed, 7 insertions(+), 42 deletions(-)
>> >
>> > diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
>> > index c14bff2cbc3..5fc9c18c81d 100644
>> > --- a/scripts/qapi/parser.py
>> > +++ b/scripts/qapi/parser.py
>> > @@ -862,49 +862,15 @@ def _insert_near_kind(
>> >                  return True
>> >          return False
>> >
>> > -    def _insert_after_intro(
>> > -        self,
>> > -        section: 'QAPIDoc.Section',
>> > -    ) -> None:
>> > -        """
>> > -        Insert a section immediately after the intro section.
>> > -
>> > -        While we convert DETAILS sections to INTRO sections, all
>> > -        contiguous INTRO/DETAILS sections at the start of a QAPIDoc
>> > -        section list are treated as "the intro".
>> > -
>> > -        Once INTRO conversion is complete, this helper will no longer be
>> > -        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.all_sections.insert(1, section)
>> > -            return
>> > -
>> > -        index = 0
>> > -        for index, ref_section in enumerate(self.all_sections):
>> > -            if ref_section.kind.name in ("INTRO", "DETAILS"):
>> > -                continue
>> > -            break
>> > -        else:
>> > -            index += 1
>> > -
>> > -        self.all_sections.insert(index, section)
>> > -
>> >      def append_member_stub(self, stub: 'QAPIDoc.Section') -> None:
>> > -
>> >          """
>> >          Append a stub section after any Member sections.
>> >          """
>> >          if self._insert_near_kind(QAPIDoc.Kind.MEMBER, stub, True):
>> >              return
>> >
>> > -        # No MEMBER sections present. Insert after INTRO/DETAILS sections.
>> > -        self._insert_after_intro(stub)
>> > +        # No MEMBER sections present. Insert after INTRO section.
>> > +        self._insert_near_kind(QAPIDoc.Kind.INTRO, stub, after=True)
>>
>> There can only be one INTRO section, and it must be first.  So this must
>> be equivalent to
>>
>>            self.all_sections.(1, stub)
>>
>> Correct?
>>
>> The argument for using the more complex ._insert_near_kind() is of
>> course symmetry with the other case.  Okay.
>>
>
> Yep, largely symmetry and opting to not write new logic as much as I can
> get away with in this patch. There's a compelling reason for not wasting
> much time writing new, cleaner logic...
>
>
>> We have three ._insert_near_kind() calls:
>>
>>         if self._insert_near_kind(QAPIDoc.Kind.MEMBER, stub, True):
>>
>>         self._insert_near_kind(QAPIDoc.Kind.INTRO, stub, after=True)
>>
>>         if any(self._insert_near_kind(kind, stub, after) for kind, after
>> in (
>>                 [...]
>>         )):
>>
>> None of them omit the optional last argument.  Two pass it positionally,
>> one as a keyword argument.  Let's dumb this down to mandatory argument.
>>
>
> I'll do you one better, that entire method goes away by the end of this
> series and we don't have to worry about it.
>
> No sense putting lipstick on the pig enroute to the slaughterhouse.

I see.

Recommend to keep the new call similar to the existing one nearby
regardless, i.e. pass True, not after=True.

[...]