Re: [PATCH 7/8] qapi: re-order 'since' sections to always be last

[John Snow <jsnow@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 2523 bytes --]

On Fri, Mar 20, 2026, 10:23 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > Note that with "Since" being moved to the last position, we open up a
> > good many new cases of ambiguos intro-vs-details text which must be
> > corrected with "Details:" tags.
> >
> > This patch doesn't only add these markers where it would definitively
> > impact inlining - it adds them to *any* doc block that has more than one
> > paragraph of plaintext and no other distinguishing features (members,
> > features, errors, returns).
> >
> > It may well be the case that not every last one of these *needs* to be
> > amended in this way, but this is the broad coverage shotgun approach
> > that demonstrates which places in the code may cause footguns with
> > regards to automated stub insertions of members/arguments/etc, returns,
> > or inlining order ambiguities.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
>
> [...]
>
> > diff --git a/qapi/accelerator.json b/qapi/accelerator.json
> > index d333a772384..5624b5d88b7 100644
> > --- a/qapi/accelerator.json
> > +++ b/qapi/accelerator.json
> > @@ -29,12 +29,12 @@
> >  #
> >  # Return information about KVM acceleration
> >  #
> > -# Since: 0.14
> > -#
> >  # .. qmp-example::
> >  #
> >  #     -> { "execute": "query-kvm" }
> >  #     <- { "return": { "enabled": true, "present": true } }
> > +#
> > +# Since: 0.14
> >  ##
> >  { 'command': 'query-kvm', 'returns': 'KvmInfo' }
> >
>
> Rendered output changes unexpectedly from
>
>     Command query-kvm (Since: 0.14)
>
>        Return information about KVM acceleration
>
>        Return:
>           KvmInfo
>
>        Example::
>
>           -> { "execute": "query-kvm" }
>           <- { "return": { "enabled": true, "present": true } }
>
> to
>
>     Command query-kvm (Since: 0.14)
>
>        Return information about KVM acceleration
>
>        Example::
>
>           -> { "execute": "query-kvm" }
>           <- { "return": { "enabled": true, "present": true } }
>
>        Return:
>           KvmInfo
>
> I guess the "Since:" quietly serves as separator between INTRO and
> DETAILS before the patch, and the patch is missing a DETAILS: line.
>
> Several more instances follow.
>
> [...]
>

Oh, drats. I suppose my yelping tool doesn't notice this kind of change in
particular.

I suppose I'll compare before/after of my .ir files and use that to
identify which cases change.

Good spot.

[-- Attachment #2: Type: text/html, Size: 3918 bytes --]