Re: [PATCH v4 7/7] qapi: convert intro sections followed by notes/examples

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> On Wed, Sep 16, 2026 at 2:13 PM Markus Armbruster <armbru@redhat.com> wrote:
>>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > These provide a rather natural cutoff point, but technically this does
>> > introduce a new intro/details split to these documentation blocks.
>>
>> Not sure what you mean by "technically".
>
> As a German, when an American says "technically", you can just omit
> that word from the sentence.
> I think, translating for you: "I don't expect these changes to have
> any immediate effect, but it's possible they might".
> You found the case where they might - a case where we probably
> actually did want a "TODO:" but never added it.
>
>>
>> >
>> > Signed-off-by: John Snow <jsnow@redhat.com>
>> > ---
>> >  qapi/machine.json   |  5 ++---
>> >  qapi/migration.json | 15 +++++++--------
>> >  qapi/misc.json      |  3 +--
>> >  qapi/run-state.json |  7 +++----
>> >  4 files changed, 13 insertions(+), 17 deletions(-)
>> >
>> > diff --git a/qapi/machine.json b/qapi/machine.json
>> > index 84d95c8d87f..276258d9e5c 100644
>> > --- a/qapi/machine.json
>> > +++ b/qapi/machine.json
>> > @@ -1209,9 +1209,8 @@
>> >
>> >  ##
>> >  # @HV_BALLOON_STATUS_REPORT:
>> > -#
>> > -# Emitted when the hv-balloon driver receives a "STATUS" message from
>> > -# the guest.
>> > +#     Emitted when the hv-balloon driver receives a "STATUS" message
>> > +#     from the guest.
>> >  #
>> >  # .. note:: This event is rate-limited.
>> >  #
>>    # Since: 8.2
>>
>> The patch splits the first section between after the first paragraph,
>> i.e. before the note.
>>
>> This matters, because we insert generated argument documentation after
>> the first section.  Rendered documentation changes like this
>>
>>     Emitted when the hv-balloon driver receives a "STATUS" message from
>>     the guest.
>>
>> +   Members:
>> +      * The members of "HvBalloonInfo".
>> +
>>     Note:
>>
>>       This event is rate-limited.
>>
>> -   Members:
>> -      * The members of "HvBalloonInfo".
>> -
>>     Example::
>>
>>        <- { "event": "HV_BALLOON_STATUS_REPORT",

Improvement, actually.

>> > diff --git a/qapi/migration.json b/qapi/migration.json
>> > index d571c06fc20..a272e701385 100644
>> > --- a/qapi/migration.json
>> > +++ b/qapi/migration.json
>> > @@ -1254,10 +1254,10 @@
>> >
>> >  ##
>> >  # @migrate_cancel:
>> > -#
>> > -# Cancel the currently executing migration process.  Allows a new
>> > -# migration to be started right after.  When postcopy-ram is in use,
>> > -# cancelling is not allowed after the postcopy phase has started.
>> > +#     Cancel the currently executing migration process.  Allows a new
>> > +#     migration to be started right after.  When postcopy-ram is in
>> > +#     use, cancelling is not allowed after the postcopy phase has
>> > +#     started.
>> >  #
>> >  # .. note:: This command succeeds even if there is no migration
>> >  #    process running.
>>
>> Similar split, but rendered documentation doesn't change, because
>> nothing gets inserted.
>>
>> Same for the remaining hunks.
>>
>> Should the one hunk that changes rendered documentation be in the "qapi:
>> convert/split remaining QAPI/QMP intro sections" series?
>
> If you should so please. I was splitting by semantics and not effect,
> but I can split this one out for you.

It's an honest question!

If you think it fits here at least as well as in the next series, keep
it here, and mention how it affects rendered documentation in the commit
message.

>
>>
>> [...]
>>