Re: [PATCH 00/14] qapi: convert to explicit intro section syntax

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> On Mon, Jul 13, 2026 at 9:00 AM Markus Armbruster <armbru@redhat.com> wrote:
>>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > GitLab CI: https://gitlab.com/jsnow/qemu/-/pipelines/2638342206
>> >
>> > Hi, this patchset converts some of the most trivial modules to use the
>> > new explicit intro syntax. This particular patchset does not
>> > differentiate between "trivial" conversions and those that take
>> > slightly more liberty in refactoring, but there are (debatably?) no
>> > such cases in this patchset.
>>
>> Looks entirely mechanical to me.  Am I missing anything?
>
> Honest answer: I am not sure; I have edited so many QAPI files that I
> cannot remember what is and what is not mechanical anymore. If there
> are instances of "non-mechanical" changes, it would be for cases where
> I decide to indent some paragraphs, but not others, effectively
> introducing a new split as to what appears before and what appears
> after the tabular data.
>
> I genuinely do not recall if there are any such cases in this mini-series.

It's only mostly mechanical.

Almost always, the patches change

  ##
  # @name:
  #
  # Single plain paragraph: Lorem ipsum dolor sit amet ut enim ad minim
  # veniam duis aute irure dolor.
  #
  # Something other than a plain paragraph

to

  ##
  # @name:
  #     Single plain paragraph: Lorem ipsum dolor sit amet ut enim ad
  #     minim veniam duis aute irure dolor.
  #
  # Something other than a plain paragraph

No decisions, thus mechanical.

I found two exceptions:

1. In qapi/compat.json

    @@ -39,8 +37,7 @@

     ##
     # @CompatPolicy:
    -#
    -# Policy for handling deprecated management interfaces.
    +#     Policy for handling deprecated management interfaces.
     #
     # This is intended for testing users of the management interfaces.
     #
     # Limitation: covers only syntactic aspects of QMP, i.e. stuff tagged
     # with feature 'deprecated' or 'unstable'.  We may want to extend it
     # to cover semantic aspects and CLI.
     #
     # Limitation: deprecated-output policy @hide is not implemented for
     # enumeration values.  They behave the same as with policy @accept.
     #
     # @deprecated-input: how to handle deprecated input (default 'accept')
     #
     # @deprecated-output: how to handle deprecated output (default
     #     'accept')
     #
     # @unstable-input: how to handle unstable input (default 'accept')
     #     (since 6.2)
     #
     # @unstable-output: how to handle unstable output (default 'accept')
     #     (since 6.2)
     #
     # Since: 6.0
     ##

   Here, we have multiple paragraphs, and only the first one becomes
   "intro".

2. In qapi/misc-arm.json

    @@ -29,9 +28,8 @@

     ##
     # @query-gic-capabilities:
    -#
    -# It will return a list of `GICCapability` objects that describe its
    -# capability bits.
    +#     It will return a list of `GICCapability` objects that describe
    +#     its capability bits.
     #
     # On non-ARM targets this command will report an error as the GIC
     # technology is not applicable.
     #
     # Since: 2.6
     #
     # .. qmp-example::
     #
     #     -> { "execute": "query-gic-capabilities" }
     #     <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
     #                     { "version": 3, "emulated": false, "kernel": true } ] }
     ##

   Here, we have two paragraphs, and both become "intro".