[PATCH v4 0/7] qapi: convert remaining "simple" intro sections

[PATCH v4 0/7] qapi: convert remaining "simple" intro sections

[John Snow]

v4:
 - :(
 - :( :(
 - Fix 'Fix python typing issue with hotfix from below ...'
v3:
 - Fix python typing issue with hotfix from below ...
 - Rebase on top of armbru/qapi-not-next
v2:
 - Fix stub insertion algorithm for some "TODO:" replacement cases

Hello, this work converts the remaining "simple" intro sections in the
QAPI schema to use the new syntax. This is part of our ongoing effort
to add the mythical "inliner" to our generated QMP documentation.

This batch covers structures that *are* likely to be inlined, and thus
have introductory paragraphs that are quite likely to be omitted when
the member documentation is copied into other contexts (e.g. as
arguments for command documentation, or as members of a branch for
commands that accept union arguments.)

"simple" here is a non-technical distinction that means a single
paragraph of text followed by an existing section boundary that
naturally already delineates what comprises the intro.

If you are a non-QAPI maintainer who has been CC'd on this series, you
may wish to review what information is being codified as the "intro"
(The indented paragraph) and keep in mind that in the future, this
text may not be visible to the end-user reading our QMP documentation
if this structure is utilized as the 'base' for another struct, used
as the arguments for a command or event, or used as branch of a
union. This series keeps it pretty simple, and every conversion herein
is being codified as "the intro", i.e. "not crucial to understanding
the behavior of the members of this struct".

This is the last of the brain-dead, simple conversions apart from any
new cases that may have been merged during the development of this
series. The remaining patches all convert or split longer paragraphs
and require more scrutiny.

We're almost back to reviewing actual code! Hang in there, everybody.

John Snow (7):
  qapi: convert remaining simple intros for block-export.json
  qapi: convert remaining simple intros for cxl.json
  qapi: convert remaining simple intros for machine.json
  qapi: convert remaining simple intros for block-core.json
  qapi/parser: fix intermediate "intro" detection
  qapi: convert intro sections with "TODO" markers
  qapi: convert intro sections followed by notes/examples

 qapi/block-core.json   | 45 ++++++++++++++++++------------------------
 qapi/block-export.json | 19 ++++++++----------
 qapi/cxl.json          | 14 +++++--------
 qapi/machine.json      | 15 +++++---------
 qapi/migration.json    | 25 +++++++++--------------
 qapi/misc.json         |  3 +--
 qapi/net.json          |  9 +++------
 qapi/run-state.json    |  7 +++----
 qapi/yank.json         |  5 +----
 scripts/qapi/parser.py |  8 ++++++++
 10 files changed, 62 insertions(+), 88 deletions(-)

-- 
2.55.0

[PATCH v4 1/7] qapi: convert remaining simple intros for block-export.json

[John Snow]

These are either structs or unions that are used in an inlinable
context: i.e. the generated documentation is likely to feature a
version of this documentation block that does not include the intro in
context of another command, event, or structure.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/block-export.json | 19 ++++++++-----------
 1 file changed, 8 insertions(+), 11 deletions(-)

diff --git a/qapi/block-export.json b/qapi/block-export.json
index 2893c6456d5..e9f7e72c8ee 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -37,10 +37,9 @@
 
 ##
 # @NbdServerOptions:
-#
-# Keep this type consistent with the `NbdServerOptionsLegacy` type.
-# The only intended difference is using `SocketAddress` instead of
-# `SocketAddressLegacy`.
+#     Keep this type consistent with the `NbdServerOptionsLegacy`
+#     type.  The only intended difference is using `SocketAddress`
+#     instead of `SocketAddressLegacy`.
 #
 # @addr: Address on which to listen (since 4.2).
 ##
@@ -50,10 +49,9 @@
 
 ##
 # @NbdServerOptionsLegacy:
-#
-# Keep this type consistent with the `NbdServerOptions` type.  The
-# only intended difference is using `SocketAddressLegacy` instead of
-# `SocketAddress`.
+#     Keep this type consistent with the `NbdServerOptions` type.  The
+#     only intended difference is using `SocketAddressLegacy` instead
+#     of `SocketAddress`.
 #
 # @addr: Address on which to listen (since 1.3).
 ##
@@ -339,9 +337,8 @@
 
 ##
 # @BlockExportOptions:
-#
-# Describes a block export, i.e. how single node should be exported on
-# an external interface.
+#     Describes a block export, i.e. how single node should be
+#     exported on an external interface.
 #
 # @type: Block export type
 #
-- 
2.55.0

[PATCH v4 2/7] qapi: convert remaining simple intros for cxl.json

[John Snow]

These are either structs or unions that are used in an inlinable
context: i.e. the generated documentation is likely to feature a
version of this documentation block that does not include the intro in
context of another command, event, or structure.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/cxl.json | 14 +++++---------
 1 file changed, 5 insertions(+), 9 deletions(-)

diff --git a/qapi/cxl.json b/qapi/cxl.json
index 631d4def2ac..9422d5a0e2d 100644
--- a/qapi/cxl.json
+++ b/qapi/cxl.json
@@ -32,9 +32,8 @@
 
 ##
 # @CXLCommonEventBase:
-#
-# Common event base for a CXL Event (CXL r3.2 8.2.10.2.1
-# Table 8-55 Common Event Record Format).
+#     Common event base for a CXL Event (CXL r3.2 8.2.10.2.1 Table
+#     8-55 Common Event Record Format).
 #
 # @path: CXL type 3 device canonical QOM path
 #
@@ -63,8 +62,7 @@
 
 ##
 # @CXLGeneralMediaEvent:
-#
-# Event record for a General Media Event (CXL r3.2 8.2.10.2.1.1).
+#     Event record for a General Media Event (CXL r3.2 8.2.10.2.1.1).
 #
 # @dpa: Device Physical Address (relative to @path device).  Note
 #     lower bits include some flags.  See CXL r3.2 Table 8-57 General
@@ -129,8 +127,7 @@
 
 ##
 # @CXLDRAMEvent:
-#
-# Event record for a DRAM Event (CXL r3.2 8.2.10.2.1.2).
+#     Event record for a DRAM Event (CXL r3.2 8.2.10.2.1.2).
 #
 # @dpa: Device Physical Address (relative to @path device).  Note
 #     lower bits include some flags.  See CXL r3.2 Table 8-58 DRAM
@@ -211,8 +208,7 @@
 
 ##
 # @CXLMemModuleEvent:
-#
-# Event record for a Memory Module Event (CXL r3.2 8.2.10.2.1.3).
+#     Event record for a Memory Module Event (CXL r3.2 8.2.10.2.1.3).
 #
 # @type: Device Event Type.  See CXL r3.2 Table 8-59 Memory Module
 #     Event Record for bit definitions for bit definiions.
-- 
2.55.0

[PATCH v4 3/7] qapi: convert remaining simple intros for machine.json

[John Snow]

These are either structs or unions that are used in an inlinable
context: i.e. the generated documentation is likely to feature a
version of this documentation block that does not include the intro in
context of another command, event, or structure.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/machine.json | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/qapi/machine.json b/qapi/machine.json
index f1f2c393824..a58e373dd70 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -449,8 +449,7 @@
 
 ##
 # @NumaOptions:
-#
-# A discriminated record of NUMA options.  (for OptsVisitor)
+#     A discriminated record of NUMA options.  (for OptsVisitor)
 #
 # @type: NUMA option type
 #
-- 
2.55.0

[PATCH v4 4/7] qapi: convert remaining simple intros for block-core.json

[John Snow]

These are either structs or unions that are used in an inlinable
context: i.e. the generated documentation is likely to feature a
version of this documentation block that does not include the intro in
context of another command, event, or structure.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/block-core.json | 45 +++++++++++++++++++-------------------------
 1 file changed, 19 insertions(+), 26 deletions(-)

diff --git a/qapi/block-core.json b/qapi/block-core.json
index 1ca147285e7..88218e38d02 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -4462,9 +4462,8 @@
 
 ##
 # @BlockdevOptionsCurlHttp:
-#
-# Driver specific block device options for HTTP connections over the
-# curl backend.  URLs must start with "http://".
+#     Driver specific block device options for HTTP connections over
+#     the curl backend.  URLs must start with "http://".
 #
 # @cookie: List of cookies to set; format is "name1=content1;
 #     name2=content2;" as explained by CURLOPT_COOKIE(3).  Defaults to
@@ -4488,9 +4487,8 @@
 
 ##
 # @BlockdevOptionsCurlHttps:
-#
-# Driver specific block device options for HTTPS connections over the
-# curl backend.  URLs must start with "https://".
+#     Driver specific block device options for HTTPS connections over
+#     the curl backend.  URLs must start with "https://".
 #
 # @sslverify: Whether to verify the SSL certificate's validity
 #     (defaults to true)
@@ -4503,9 +4501,8 @@
 
 ##
 # @BlockdevOptionsCurlFtp:
-#
-# Driver specific block device options for FTP connections over the
-# curl backend.  URLs must start with "ftp://".
+#     Driver specific block device options for FTP connections over
+#     the curl backend.  URLs must start with "ftp://".
 #
 # Since: 2.9
 ##
@@ -4515,9 +4512,8 @@
 
 ##
 # @BlockdevOptionsCurlFtps:
-#
-# Driver specific block device options for FTPS connections over the
-# curl backend.  URLs must start with "ftps://".
+#     Driver specific block device options for FTPS connections over
+#     the curl backend.  URLs must start with "ftps://".
 #
 # @sslverify: Whether to verify the SSL certificate's validity
 #     (defaults to true)
@@ -4643,14 +4639,13 @@
 
 ##
 # @BlockdevOptionsCbw:
-#
-# Driver specific block device options for the copy-before-write
-# driver, which does so called copy-before-write operations: when data
-# is written to the filter, the filter first reads corresponding
-# blocks from its file child and copies them to @target child.  After
-# successfully copying, the write request is propagated to file child.
-# If copying fails, the original write request is failed too and no
-# data is written to file child.
+#     Driver specific block device options for the copy-before-write
+#     driver, which does so called copy-before-write operations: when
+#     data is written to the filter, the filter first reads
+#     corresponding blocks from its file child and copies them to
+#     @target child.  After successfully copying, the write request is
+#     propagated to file child.  If copying fails, the original write
+#     request is failed too and no data is written to file child.
 #
 # @target: The target for copy-before-write operations.
 #
@@ -4686,9 +4681,8 @@
 
 ##
 # @BlockdevOptions:
-#
-# Options for creating a block device.  Many options are available for
-# all block devices, independent of the block driver:
+#     Options for creating a block device.  Many options are available
+#     for all block devices, independent of the block driver:
 #
 # @driver: block driver name
 #
@@ -5473,9 +5467,8 @@
 
 ##
 # @BlockdevAmendOptionsQcow2:
-#
-# Driver specific image amend options for qcow2.  For now, only
-# encryption options can be amended
+#     Driver specific image amend options for qcow2.  For now, only
+#     encryption options can be amended
 #
 # @encrypt: Encryption options to be amended
 #
-- 
2.55.0

[PATCH v4 5/7] qapi/parser: fix intermediate "intro" detection

[John Snow]

In 43e7ad1a3fa5, I adjusted the insertion algorithm for inserting
something after the "introduction" to cope with both the old and new
syntax while we converted QAPI to the new syntax. There's a bug in
that code that only shows up in a handful of cases and only when using
the new syntax while this affordance/flex code is still enabled.

In the case that we do actually have a real bona-fide intro section,
we want to insert directly after that real-deal intro section, not
after any plaintext sections that may follow it. This code adjusts the
temporary code to strongly prefer inserting after the actual intro
section if it exists.

Once again: once conversion is done, you will be delighted by how much
of this ugly code goes away.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 scripts/qapi/parser.py | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 9e14c2f7921..6a9a5589c14 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -845,6 +845,14 @@ def _insert_after_intro(
         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._insert_near_kind(QAPIDoc.Kind.INTRO, section, after=True)
+            return
+
         index = 0
         for index, ref_section in enumerate(self.all_sections):
             if ref_section.kind.name in ("PLAIN", "INTRO"):
-- 
2.55.0

[PATCH v4 6/7] qapi: convert intro sections with "TODO" markers

[John Snow]

This patch converts intro sections that are immediately followed by a
"TODO:" that was formerly used to demarcate the stub member insertion
point.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/machine.json   |  7 ++-----
 qapi/migration.json | 10 ++--------
 qapi/net.json       |  9 +++------
 qapi/yank.json      |  5 +----
 4 files changed, 8 insertions(+), 23 deletions(-)

diff --git a/qapi/machine.json b/qapi/machine.json
index a58e373dd70..84d95c8d87f 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1244,11 +1244,8 @@
 
 ##
 # @query-memory-size-summary:
-#
-# Return the amount of initially allocated and present hotpluggable
-# (if enabled) memory in bytes.
-#
-# TODO: This line is a hack to separate the example from the body
+#     Return the amount of initially allocated and present
+#     hotpluggable (if enabled) memory in bytes.
 #
 # .. qmp-example::
 #
diff --git a/qapi/migration.json b/qapi/migration.json
index 0428f777882..d571c06fc20 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -1617,10 +1617,7 @@
 
 ##
 # @query-xen-replication-status:
-#
-# Query replication status while the vm is running.
-#
-# TODO: This line is a hack to separate the example from the body
+#     Query replication status while the vm is running.
 #
 # .. qmp-example::
 #
@@ -1670,10 +1667,7 @@
 
 ##
 # @query-colo-status:
-#
-# Query COLO status while the vm is running.
-#
-# TODO: This line is a hack to separate the example from the body
+#     Query COLO status while the vm is running.
 #
 # .. qmp-example::
 #
diff --git a/qapi/net.json b/qapi/net.json
index 526108ca0bb..d0bacb4dcfe 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -1159,12 +1159,9 @@
 
 ##
 # @announce-self:
-#
-# Trigger generation of broadcast RARP frames to update network
-# switches.  This can be useful when network bonds fail-over the
-# active slave.
-#
-# TODO: This line is a hack to separate the example from the body
+#     Trigger generation of broadcast RARP frames to update network
+#     switches.  This can be useful when network bonds fail-over the
+#     active slave.
 #
 # .. qmp-example::
 #
diff --git a/qapi/yank.json b/qapi/yank.json
index 8ac4b773653..187a0952e66 100644
--- a/qapi/yank.json
+++ b/qapi/yank.json
@@ -96,10 +96,7 @@
 
 ##
 # @query-yank:
-#
-# Query yank instances.  See `YankInstance` for more information.
-#
-# TODO: This line is a hack to separate the example from the body
+#     Query yank instances.  See `YankInstance` for more information.
 #
 # .. qmp-example::
 #
-- 
2.55.0

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

[John Snow]

These provide a rather natural cutoff point, but technically this does
introduce a new intro/details split to these documentation blocks.

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.
 #
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.
@@ -1632,8 +1632,8 @@
 
 ##
 # @xen-colo-do-checkpoint:
-#
-# Xen uses this command to notify replication to trigger a checkpoint.
+#     Xen uses this command to notify replication to trigger a
+#     checkpoint.
 #
 # .. qmp-example::
 #
@@ -1700,8 +1700,7 @@
 
 ##
 # @migrate-pause:
-#
-# Pause a migration.  Currently it only supports postcopy.
+#     Pause a migration.  Currently it only supports postcopy.
 #
 # .. qmp-example::
 #
diff --git a/qapi/misc.json b/qapi/misc.json
index b7d08532768..b62cabc2b79 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -103,8 +103,7 @@
 
 ##
 # @query-iothreads:
-#
-# Return a list of information about each iothread.
+#     Return a list of information about each iothread.
 #
 # .. note:: This list excludes the QEMU main loop thread, which is not
 #    declared using the ``-object iothread`` command-line option.  It
diff --git a/qapi/run-state.json b/qapi/run-state.json
index 703ca1bb5b9..8bbd9884087 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -232,10 +232,9 @@
 
 ##
 # @SUSPEND_DISK:
-#
-# Emitted when guest enters a hardware suspension state with data
-# saved on disk, for example, S4 state, which is sometimes called
-# hibernate state
+#     Emitted when guest enters a hardware suspension state with data
+#     saved on disk, for example, S4 state, which is sometimes called
+#     hibernate state
 #
 # .. note:: QEMU shuts down (similar to event `SHUTDOWN`) when
 #    entering this state.
-- 
2.55.0

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

[Markus Armbruster]

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".

>
> 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",

> 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?

[...]

Re: [PATCH v4 5/7] qapi/parser: fix intermediate "intro" detection

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> In 43e7ad1a3fa5, I adjusted the insertion algorithm for inserting
> something after the "introduction" to cope with both the old and new
> syntax while we converted QAPI to the new syntax. There's a bug in
> that code that only shows up in a handful of cases and only when using
> the new syntax while this affordance/flex code is still enabled.
>
> In the case that we do actually have a real bona-fide intro section,
> we want to insert directly after that real-deal intro section, not
> after any plaintext sections that may follow it. This code adjusts the
> temporary code to strongly prefer inserting after the actual intro
> section if it exists.
>
> Once again: once conversion is done, you will be delighted by how much
> of this ugly code goes away.
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  scripts/qapi/parser.py | 8 ++++++++
>  1 file changed, 8 insertions(+)
>
> diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
> index 9e14c2f7921..6a9a5589c14 100644
> --- a/scripts/qapi/parser.py
> +++ b/scripts/qapi/parser.py
> @@ -845,6 +845,14 @@ def _insert_after_intro(
>          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._insert_near_kind(QAPIDoc.Kind.INTRO, section, after=True)

Isn't this a roundabout way to do

               self.all_sections.insert(1, section)

?

> +            return
> +
>          index = 0
>          for index, ref_section in enumerate(self.all_sections):
>              if ref_section.kind.name in ("PLAIN", "INTRO"):
                   continue
               break
           else:
               index += 1

           self.all_sections.insert(index, section)

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

[John Snow]

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",
>
> > 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.

>
> [...]
>

Re: [PATCH v4 5/7] qapi/parser: fix intermediate "intro" detection

[John Snow]

On Thu, Sep 17, 2026 at 1:13 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> John Snow <jsnow@redhat.com> writes:
>
> > In 43e7ad1a3fa5, I adjusted the insertion algorithm for inserting
> > something after the "introduction" to cope with both the old and new
> > syntax while we converted QAPI to the new syntax. There's a bug in
> > that code that only shows up in a handful of cases and only when using
> > the new syntax while this affordance/flex code is still enabled.
> >
> > In the case that we do actually have a real bona-fide intro section,
> > we want to insert directly after that real-deal intro section, not
> > after any plaintext sections that may follow it. This code adjusts the
> > temporary code to strongly prefer inserting after the actual intro
> > section if it exists.
> >
> > Once again: once conversion is done, you will be delighted by how much
> > of this ugly code goes away.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> >  scripts/qapi/parser.py | 8 ++++++++
> >  1 file changed, 8 insertions(+)
> >
> > diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
> > index 9e14c2f7921..6a9a5589c14 100644
> > --- a/scripts/qapi/parser.py
> > +++ b/scripts/qapi/parser.py
> > @@ -845,6 +845,14 @@ def _insert_after_intro(
> >          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._insert_near_kind(QAPIDoc.Kind.INTRO, section, after=True)
>
> Isn't this a roundabout way to do
>
>                self.all_sections.insert(1, section)
>
> ?

Yes O:-)

... but it's the more semantically abstracted version that does not
rely on the specific location of the section. By the end of the
next-next series, all of this goes away anyway. I think I was
preferring to avoid using insert in more than the two helpers we
already use it in. (But since I intend to delete it all, I don't
really care about fighting for purity in isolating this call.)

Specifically:

_insert_near_kind(), _insert_after_intro() both go away.
append_member_stub() also goes away. ensure_returns() stays but
becomes something like two lines.

*all* section modification in the next-next series happens exclusively
through a method named `_append()` which Does The Right Thing In All
Cases.

--js

>
> > +            return
> > +
> >          index = 0
> >          for index, ref_section in enumerate(self.all_sections):
> >              if ref_section.kind.name in ("PLAIN", "INTRO"):
>                    continue
>                break
>            else:
>                index += 1
>
>            self.all_sections.insert(index, section)
>

Re: [PATCH v4 5/7] qapi/parser: fix intermediate "intro" detection

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> On Thu, Sep 17, 2026 at 1:13 AM Markus Armbruster <armbru@redhat.com> wrote:
>>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > In 43e7ad1a3fa5, I adjusted the insertion algorithm for inserting
>> > something after the "introduction" to cope with both the old and new
>> > syntax while we converted QAPI to the new syntax. There's a bug in
>> > that code that only shows up in a handful of cases and only when using
>> > the new syntax while this affordance/flex code is still enabled.
>> >
>> > In the case that we do actually have a real bona-fide intro section,
>> > we want to insert directly after that real-deal intro section, not
>> > after any plaintext sections that may follow it. This code adjusts the
>> > temporary code to strongly prefer inserting after the actual intro
>> > section if it exists.
>> >
>> > Once again: once conversion is done, you will be delighted by how much
>> > of this ugly code goes away.
>> >
>> > Signed-off-by: John Snow <jsnow@redhat.com>
>> > ---
>> >  scripts/qapi/parser.py | 8 ++++++++
>> >  1 file changed, 8 insertions(+)
>> >
>> > diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
>> > index 9e14c2f7921..6a9a5589c14 100644
>> > --- a/scripts/qapi/parser.py
>> > +++ b/scripts/qapi/parser.py
>> > @@ -845,6 +845,14 @@ def _insert_after_intro(
>> >          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._insert_near_kind(QAPIDoc.Kind.INTRO, section, after=True)
>>
>> Isn't this a roundabout way to do
>>
>>                self.all_sections.insert(1, section)
>>
>> ?
>
> Yes O:-)
>
> ... but it's the more semantically abstracted version that does not
> rely on the specific location of the section. By the end of the
> next-next series, all of this goes away anyway. I think I was
> preferring to avoid using insert in more than the two helpers we
> already use it in. (But since I intend to delete it all, I don't
> really care about fighting for purity in isolating this call.)
>
> Specifically:
>
> _insert_near_kind(), _insert_after_intro() both go away.
> append_member_stub() also goes away. ensure_returns() stays but
> becomes something like two lines.
>
> *all* section modification in the next-next series happens exclusively
> through a method named `_append()` which Does The Right Thing In All
> Cases.
>
> --js

What caught my eye was the dissonance between self._insert_near_kind()
above and self.all_sections.insert() below.

Then I looked at ._insert_near_kind().  It inserts before or after the
last section of a certain kind.  Here, it inserts after the last INTRO.
Since we always have exactly INTRO, and it always comes first, it
inserts after the first section.  Just what the comment says.  Good.
But why not just do what the comment says in the most straightforward
way possible?  Am I missing something?  Thus my question.

>>
>> > +            return
>> > +
>> >          index = 0
>> >          for index, ref_section in enumerate(self.all_sections):
>> >              if ref_section.kind.name in ("PLAIN", "INTRO"):
>>                    continue
>>                break
>>            else:
>>                index += 1
>>
>>            self.all_sections.insert(index, section)
>>

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

[Markus Armbruster]

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.

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