John Snow <[email protected]> writes:
> On Mon, Jul 13, 2026 at 9:00 AM Markus Armbruster <[email protected]> wrote:
>>
>> John Snow <[email protected]> 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".
