[PATCH 0/9] qapi: convert/split remaining QAPI/QMP intro sections

[PATCH 0/9] qapi: convert/split remaining QAPI/QMP intro sections

[John Snow]

Give or take any that snuck in during this conversion marathon, this
should be the rest - and the trickiest ones that involve multiple
paragraphs and decisions over where exactly to place the
split. Currently there are no prose rewrites, but it is not out of the
question that we will require some after review.

If you are a non-QAPI maintainer, the TL:DR here is:
    Take a look at what is being indented here and what is
    not. Anything that gets indented is text that is not eligible for
    inlining: that is, the intro text is not copied into command/event
    documentation to replace "The members of ..." placeholders in our
    generated documentation.

    If any text that you believe is important for end users to
    understand is in the indented section after these patches, please
    review and propose a different prose split.

    (More info: The intro text is not guaranteed to be dropped from
    generated docs. For example, if a struct is used as a type for an
    argument in its own right, it is guaranteed to be included in the
    generated documentation. It is also always included for commands,
    events, and enums. It is only for structs which are *only* ever
    used as command/event arguments or as a branch type where this
    text is at risk of not being reproduced at all in the output
    documentation.)

John Snow (9):
  qapi: convert remaining simple intros for block-export.json
  qapi: convert multi-paragraph intros (commands)
  qapi: convert multi-paragraph intros (enums)
  qapi: convert multi-paragraph intros (structs)
  qapi: split intro sections for commands
  qapi: split intro sections for events
  qapi: split intro sections for enums
  qapi: split intro sections for data structs
  qapi: split intro sections for inlinable structs

 qapi/acpi.json          |   3 +-
 qapi/block-core.json    | 130 ++++++++++++++++++----------------------
 qapi/block-export.json  |  27 ++++-----
 qapi/block.json         |  71 +++++++++++-----------
 qapi/compat.json        |   3 +-
 qapi/control.json       |   3 +-
 qapi/crypto.json        |   3 +-
 qapi/introspect.json    |  16 ++---
 qapi/job.json           |  43 ++++++-------
 qapi/machine-s390x.json |   3 +-
 qapi/machine.json       |  98 +++++++++++++++---------------
 qapi/migration.json     |  18 +++---
 qapi/misc-arm.json      |   9 ++-
 qapi/misc-i386.json     |  22 +++----
 qapi/misc.json          |  18 +++---
 qapi/net.json           |  37 +++++-------
 qapi/qdev.json          |  14 ++---
 qapi/qom.json           |  27 ++++-----
 qapi/stats.json         |   5 +-
 qapi/transaction.json   |   6 +-
 qapi/ui.json            |   8 +--
 21 files changed, 253 insertions(+), 311 deletions(-)

-- 
2.55.0

[PATCH 1/9] 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

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

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

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

This patch is also in "[PATCH 0/6] qapi: convert remaining "simple"
intro sections".  I believe it's included here accidentally.  Harmless
:)

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

[John Snow]

On Sat, Sep 12, 2026 at 3:02 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> John Snow <jsnow@redhat.com> writes:
>
> > 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>
>
> This patch is also in "[PATCH 0/6] qapi: convert remaining "simple"
> intro sections".  I believe it's included here accidentally.  Harmless
> :)

Yes, oops. Too far down the rebase chain.

[PATCH 2/9] qapi: convert multi-paragraph intros (commands)

[John Snow]

This patch converts some slightly-non-trivial intros with more than
one paragraph, but doesn't create any new intro/details splits.

Review notes: Some of these possibly could be split, but as they are commands
(not eligible as an inlining source) and the additional information in
the intro is not terribly long, I opted to leave them alone instead of
laboring on prose rewrites.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/block-core.json | 49 +++++++++++++++++++++-----------------------
 qapi/block.json      | 29 +++++++++++++-------------
 qapi/migration.json  |  9 ++++----
 qapi/misc-arm.json   |  9 ++++----
 qapi/misc.json       | 13 ++++++------
 qapi/qdev.json       | 14 ++++++-------
 6 files changed, 58 insertions(+), 65 deletions(-)

diff --git a/qapi/block-core.json b/qapi/block-core.json
index 1ca147285e7..c505369aeb2 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1772,13 +1772,12 @@
 
 ##
 # @blockdev-snapshot:
+#     Takes a snapshot of a block device.
 #
-# Takes a snapshot of a block device.
-#
-# Take a snapshot, by installing 'node' as the backing image of
-# 'overlay'.  Additionally, if 'node' is associated with a block
-# device, the block device changes to using 'overlay' as its new
-# active image.
+#     Take a snapshot, by installing 'node' as the backing image of
+#     'overlay'.  Additionally, if 'node' is associated with a block
+#     device, the block device changes to using 'overlay' as its new
+#     active image.
 #
 # Features:
 #
@@ -2471,15 +2470,15 @@
 ##
 # @block-dirty-bitmap-merge:
 #
-# Merge dirty bitmaps listed in @bitmaps to the @target dirty bitmap.
-# Dirty bitmaps in @bitmaps will be unchanged, except if it also
-# appears as the @target bitmap.  Any bits already set in @target will
-# still be set after the merge, i.e., this operation does not clear
-# the target.  On error, @target is unchanged.
+#     Merge dirty bitmaps listed in @bitmaps to the @target dirty
+#     bitmap.  Dirty bitmaps in @bitmaps will be unchanged, except if
+#     it also appears as the @target bitmap.  Any bits already set in
+#     @target will still be set after the merge, i.e., this operation
+#     does not clear the target.  On error, @target is unchanged.
 #
-# The resulting bitmap will count as dirty any clusters that were
-# dirty in any of the source bitmaps.  This can be used to achieve
-# backup checkpoints, or in simpler usages, to copy bitmaps.
+#     The resulting bitmap will count as dirty any clusters that were
+#     dirty in any of the source bitmaps.  This can be used to achieve
+#     backup checkpoints, or in simpler usages, to copy bitmaps.
 #
 # Errors:
 #     - If @node is not a valid block device, DeviceNotFound
@@ -5848,15 +5847,14 @@
 
 ##
 # @block-set-write-threshold:
+#     Change the write threshold for a block drive.  An event will be
+#     delivered if a write to this block drive crosses the configured
+#     threshold.  The threshold is an offset, thus must be
+#     non-negative.  Default is no write threshold.  Setting the
+#     threshold to zero disables it.
 #
-# Change the write threshold for a block drive.  An event will be
-# delivered if a write to this block drive crosses the configured
-# threshold.  The threshold is an offset, thus must be non-negative.
-# Default is no write threshold.  Setting the threshold to zero
-# disables it.
-#
-# This is useful to transparently resize thin-provisioned drives
-# without the guest OS noticing.
+#     This is useful to transparently resize thin-provisioned drives
+#     without the guest OS noticing.
 #
 # @node-name: graph node name on which the threshold must be set.
 #
@@ -5938,11 +5936,10 @@
 
 ##
 # @x-blockdev-set-iothread:
+#     Move @node and its children into the @iothread.  If @iothread is
+#     null then move @node and its children into the main loop.
 #
-# Move @node and its children into the @iothread.  If @iothread is
-# null then move @node and its children into the main loop.
-#
-# The node must not be attached to a BlockBackend.
+#     The node must not be attached to a BlockBackend.
 #
 # @node-name: the name of the block driver node
 #
diff --git a/qapi/block.json b/qapi/block.json
index e47592d5500..15f08372564 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -181,12 +181,13 @@
 
 ##
 # @blockdev-close-tray:
+#     Closes a block device's tray.
 #
-# Closes a block device's tray.  If there is a block driver state tree
-# associated with the block device (which is currently ejected), that
-# tree will be loaded as the medium.
+#     If there is a block driver state tree associated with the block
+#     device (which is currently ejected), that tree will be loaded as
+#     the medium.
 #
-# If the tray was already closed before, this will be a no-op.
+#     If the tray was already closed before, this will be a no-op.
 #
 # @device: Block device name
 #
@@ -218,13 +219,12 @@
 
 ##
 # @blockdev-remove-medium:
+#     Removes a medium (a block driver state tree) from a block
+#     device.  That block device's tray must currently be open
+#     (unless there is no attached guest device).
 #
-# Removes a medium (a block driver state tree) from a block device.
-# That block device's tray must currently be open (unless there is no
-# attached guest device).
-#
-# If the tray is open and there is no medium inserted, this will be a
-# no-op.
+#     If the tray is open and there is no medium inserted, this will
+#     be a no-op.
 #
 # @id: The name or QOM path of the guest device
 #
@@ -504,12 +504,11 @@
 
 ##
 # @block-latency-histogram-set:
+#     Manage read, write and flush latency histograms for the device.
 #
-# Manage read, write and flush latency histograms for the device.
-#
-# If only @id parameter is specified, remove all present latency
-# histograms for the device.  Otherwise, add/reset some of (or all)
-# latency histograms.
+#     If only @id parameter is specified, remove all present latency
+#     histograms for the device.  Otherwise, add/reset some of (or
+#     all) latency histograms.
 #
 # @id: The name or QOM path of the guest device.
 #
diff --git a/qapi/migration.json b/qapi/migration.json
index 8096ef64682..13c446b922f 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -1965,12 +1965,11 @@
 
 ##
 # @cancel-vcpu-dirty-limit:
+#     Cancel the upper limit of dirty page rate for virtual CPUs.
 #
-# Cancel the upper limit of dirty page rate for virtual CPUs.
-#
-# Cancel the dirty page limit for the vCPU which has been set with
-# `set-vcpu-dirty-limit` command.  Note that this command requires
-# support from dirty ring, same as the `set-vcpu-dirty-limit`.
+#     Cancel the dirty page limit for the vCPU which has been set with
+#     `set-vcpu-dirty-limit` command.  Note that this command requires
+#     support from dirty ring, same as the `set-vcpu-dirty-limit`.
 #
 # @cpu-index: index of a virtual CPU, default is all.
 #
diff --git a/qapi/misc-arm.json b/qapi/misc-arm.json
index 8cb2ea77951..64059b5688d 100644
--- a/qapi/misc-arm.json
+++ b/qapi/misc-arm.json
@@ -28,12 +28,11 @@
 
 ##
 # @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.
+#     On non-ARM targets this command will report an error as the GIC
+#     technology is not applicable.
 #
 # Since: 2.6
 #
diff --git a/qapi/misc.json b/qapi/misc.json
index b3c2a1421f3..374711ac6c7 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -178,14 +178,13 @@
 
 ##
 # @x-exit-preconfig:
+#     Exit from "preconfig" state
 #
-# Exit from "preconfig" state
-#
-# This command makes QEMU exit the preconfig state and proceed with VM
-# initialization using configuration data provided on the command line
-# and via the QMP monitor during the preconfig state.  The command is
-# only available during the preconfig state (i.e. when the --preconfig
-# command line option was in use).
+#     This command makes QEMU exit the preconfig state and proceed
+#     with VM initialization using configuration data provided on the
+#     command line and via the QMP monitor during the preconfig state.
+#     The command is only available during the preconfig state
+#     (i.e. when the --preconfig command line option was in use).
 #
 # Features:
 #
diff --git a/qapi/qdev.json b/qapi/qdev.json
index a35321d2fd1..e19a92a44e8 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -163,14 +163,14 @@
 ##
 # @device-sync-config:
 #
-# Synchronize device configuration from host to guest part.  First,
-# copy the configuration from the host part (backend) to the guest
-# part (frontend).  Then notify guest software that device
-# configuration changed.
+#     Synchronize device configuration from host to guest part.
+#     First, copy the configuration from the host part (backend) to
+#     the guest part (frontend).  Then notify guest software that
+#     device configuration changed.
 #
-# The command may be used to notify the guest about block device
-# capacity change.  Currently only vhost-user-blk device supports
-# this.
+#     The command may be used to notify the guest about block device
+#     capacity change.  Currently only vhost-user-blk device supports
+#     this.
 #
 # @id: the device's ID or QOM path
 #
-- 
2.55.0

Re: [PATCH 2/9] qapi: convert multi-paragraph intros (commands)

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> This patch converts some slightly-non-trivial intros with more than
> one paragraph, but doesn't create any new intro/details splits.
>
> Review notes: Some of these possibly could be split, but as they are commands
> (not eligible as an inlining source) and the additional information in
> the intro is not terribly long, I opted to leave them alone instead of
> laboring on prose rewrites.
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/block-core.json | 49 +++++++++++++++++++++-----------------------
>  qapi/block.json      | 29 +++++++++++++-------------
>  qapi/migration.json  |  9 ++++----
>  qapi/misc-arm.json   |  9 ++++----
>  qapi/misc.json       | 13 ++++++------
>  qapi/qdev.json       | 14 ++++++-------
>  6 files changed, 58 insertions(+), 65 deletions(-)
>
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index 1ca147285e7..c505369aeb2 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -1772,13 +1772,12 @@
>  
>  ##
>  # @blockdev-snapshot:
> +#     Takes a snapshot of a block device.
>  #
> -# Takes a snapshot of a block device.
> -#
> -# Take a snapshot, by installing 'node' as the backing image of
> -# 'overlay'.  Additionally, if 'node' is associated with a block
> -# device, the block device changes to using 'overlay' as its new
> -# active image.
> +#     Take a snapshot, by installing 'node' as the backing image of
> +#     'overlay'.  Additionally, if 'node' is associated with a block
> +#     device, the block device changes to using 'overlay' as its new
> +#     active image.

'overlay' and 'node' refer to arguments, so they should be @overlay and
@node.  Since the arguments are in type BlockdevSnapshot, the reference
is non-local until the inliner lands.

We may want to render this paragraph below the argument descriptions to
avoid forward references.  This requires splitting it off the intro.  We
can do it now, or leave it for later.

Not splitting now keeps the conversion simple, which is a plus.  It
reindents the entire unsplit intro, and if we do split it later, the
part split off gets reindented right back.

I'm leaning towards not rocking the boat, but you decide.

Not noting these things again.

>  #
>  # Features:
>  #
> @@ -2471,15 +2470,15 @@
>  ##
>  # @block-dirty-bitmap-merge:
>  #

Drop the blank line.

> -# Merge dirty bitmaps listed in @bitmaps to the @target dirty bitmap.
> -# Dirty bitmaps in @bitmaps will be unchanged, except if it also
> -# appears as the @target bitmap.  Any bits already set in @target will
> -# still be set after the merge, i.e., this operation does not clear
> -# the target.  On error, @target is unchanged.
> +#     Merge dirty bitmaps listed in @bitmaps to the @target dirty
> +#     bitmap.  Dirty bitmaps in @bitmaps will be unchanged, except if
> +#     it also appears as the @target bitmap.  Any bits already set in
> +#     @target will still be set after the merge, i.e., this operation
> +#     does not clear the target.  On error, @target is unchanged.
>  #
> -# The resulting bitmap will count as dirty any clusters that were
> -# dirty in any of the source bitmaps.  This can be used to achieve
> -# backup checkpoints, or in simpler usages, to copy bitmaps.
> +#     The resulting bitmap will count as dirty any clusters that were
> +#     dirty in any of the source bitmaps.  This can be used to achieve
> +#     backup checkpoints, or in simpler usages, to copy bitmaps.
>  #
>  # Errors:
>  #     - If @node is not a valid block device, DeviceNotFound
> @@ -5848,15 +5847,14 @@
>  
>  ##
>  # @block-set-write-threshold:
> +#     Change the write threshold for a block drive.  An event will be
> +#     delivered if a write to this block drive crosses the configured
> +#     threshold.  The threshold is an offset, thus must be
> +#     non-negative.  Default is no write threshold.  Setting the
> +#     threshold to zero disables it.
>  #
> -# Change the write threshold for a block drive.  An event will be
> -# delivered if a write to this block drive crosses the configured
> -# threshold.  The threshold is an offset, thus must be non-negative.
> -# Default is no write threshold.  Setting the threshold to zero
> -# disables it.
> -#
> -# This is useful to transparently resize thin-provisioned drives
> -# without the guest OS noticing.
> +#     This is useful to transparently resize thin-provisioned drives
> +#     without the guest OS noticing.
>  #
>  # @node-name: graph node name on which the threshold must be set.
>  #
> @@ -5938,11 +5936,10 @@
>  
>  ##
>  # @x-blockdev-set-iothread:
> +#     Move @node and its children into the @iothread.  If @iothread is
> +#     null then move @node and its children into the main loop.
>  #
> -# Move @node and its children into the @iothread.  If @iothread is
> -# null then move @node and its children into the main loop.
> -#
> -# The node must not be attached to a BlockBackend.
> +#     The node must not be attached to a BlockBackend.

This one arguably lacks an intro.  Let's not worry about this now.

>  #
>  # @node-name: the name of the block driver node
>  #
> diff --git a/qapi/block.json b/qapi/block.json
> index e47592d5500..15f08372564 100644
> --- a/qapi/block.json
> +++ b/qapi/block.json
> @@ -181,12 +181,13 @@
>  
>  ##
>  # @blockdev-close-tray:
> +#     Closes a block device's tray.
>  #
> -# Closes a block device's tray.  If there is a block driver state tree
> -# associated with the block device (which is currently ejected), that
> -# tree will be loaded as the medium.
> +#     If there is a block driver state tree associated with the block
> +#     device (which is currently ejected), that tree will be loaded as
> +#     the medium.
>  #
> -# If the tray was already closed before, this will be a no-op.
> +#     If the tray was already closed before, this will be a no-op.
>  #
>  # @device: Block device name
>  #

Shouldn't this one be in "[PATCH 5/9] qapi: split intro sections for
commands"?

> @@ -218,13 +219,12 @@
>  
>  ##
>  # @blockdev-remove-medium:
> +#     Removes a medium (a block driver state tree) from a block
> +#     device.  That block device's tray must currently be open
> +#     (unless there is no attached guest device).
>  #
> -# Removes a medium (a block driver state tree) from a block device.
> -# That block device's tray must currently be open (unless there is no
> -# attached guest device).
> -#
> -# If the tray is open and there is no medium inserted, this will be a
> -# no-op.
> +#     If the tray is open and there is no medium inserted, this will
> +#     be a no-op.
>  #
>  # @id: The name or QOM path of the guest device
>  #
> @@ -504,12 +504,11 @@
>  
>  ##
>  # @block-latency-histogram-set:
> +#     Manage read, write and flush latency histograms for the device.
>  #
> -# Manage read, write and flush latency histograms for the device.
> -#
> -# If only @id parameter is specified, remove all present latency
> -# histograms for the device.  Otherwise, add/reset some of (or all)
> -# latency histograms.
> +#     If only @id parameter is specified, remove all present latency
> +#     histograms for the device.  Otherwise, add/reset some of (or
> +#     all) latency histograms.
>  #
>  # @id: The name or QOM path of the guest device.
>  #
> diff --git a/qapi/migration.json b/qapi/migration.json
> index 8096ef64682..13c446b922f 100644
> --- a/qapi/migration.json
> +++ b/qapi/migration.json
> @@ -1965,12 +1965,11 @@
>  
>  ##
>  # @cancel-vcpu-dirty-limit:
> +#     Cancel the upper limit of dirty page rate for virtual CPUs.
>  #
> -# Cancel the upper limit of dirty page rate for virtual CPUs.
> -#
> -# Cancel the dirty page limit for the vCPU which has been set with
> -# `set-vcpu-dirty-limit` command.  Note that this command requires
> -# support from dirty ring, same as the `set-vcpu-dirty-limit`.
> +#     Cancel the dirty page limit for the vCPU which has been set with
> +#     `set-vcpu-dirty-limit` command.  Note that this command requires
> +#     support from dirty ring, same as the `set-vcpu-dirty-limit`.
>  #
>  # @cpu-index: index of a virtual CPU, default is all.
>  #
> diff --git a/qapi/misc-arm.json b/qapi/misc-arm.json
> index 8cb2ea77951..64059b5688d 100644
> --- a/qapi/misc-arm.json
> +++ b/qapi/misc-arm.json
> @@ -28,12 +28,11 @@
>  
>  ##
>  # @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.
> +#     On non-ARM targets this command will report an error as the GIC
> +#     technology is not applicable.
>  #
>  # Since: 2.6
>  #
> diff --git a/qapi/misc.json b/qapi/misc.json
> index b3c2a1421f3..374711ac6c7 100644
> --- a/qapi/misc.json
> +++ b/qapi/misc.json
> @@ -178,14 +178,13 @@
>  
>  ##
>  # @x-exit-preconfig:
> +#     Exit from "preconfig" state
>  #
> -# Exit from "preconfig" state
> -#
> -# This command makes QEMU exit the preconfig state and proceed with VM
> -# initialization using configuration data provided on the command line
> -# and via the QMP monitor during the preconfig state.  The command is
> -# only available during the preconfig state (i.e. when the --preconfig
> -# command line option was in use).
> +#     This command makes QEMU exit the preconfig state and proceed
> +#     with VM initialization using configuration data provided on the
> +#     command line and via the QMP monitor during the preconfig state.
> +#     The command is only available during the preconfig state
> +#     (i.e. when the --preconfig command line option was in use).
>  #
>  # Features:
>  #
> diff --git a/qapi/qdev.json b/qapi/qdev.json
> index a35321d2fd1..e19a92a44e8 100644
> --- a/qapi/qdev.json
> +++ b/qapi/qdev.json
> @@ -163,14 +163,14 @@
>  ##
>  # @device-sync-config:
>  #

Drop the blank line.

> -# Synchronize device configuration from host to guest part.  First,
> -# copy the configuration from the host part (backend) to the guest
> -# part (frontend).  Then notify guest software that device
> -# configuration changed.
> +#     Synchronize device configuration from host to guest part.
> +#     First, copy the configuration from the host part (backend) to
> +#     the guest part (frontend).  Then notify guest software that
> +#     device configuration changed.
>  #
> -# The command may be used to notify the guest about block device
> -# capacity change.  Currently only vhost-user-blk device supports
> -# this.
> +#     The command may be used to notify the guest about block device
> +#     capacity change.  Currently only vhost-user-blk device supports
> +#     this.
>  #
>  # @id: the device's ID or QOM path
>  #

Re: [PATCH 2/9] qapi: convert multi-paragraph intros (commands)

[John Snow]

On Wed, Sep 16, 2026 at 5:38 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> John Snow <jsnow@redhat.com> writes:
>
> > This patch converts some slightly-non-trivial intros with more than
> > one paragraph, but doesn't create any new intro/details splits.
> >
> > Review notes: Some of these possibly could be split, but as they are commands
> > (not eligible as an inlining source) and the additional information in
> > the intro is not terribly long, I opted to leave them alone instead of
> > laboring on prose rewrites.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> >  qapi/block-core.json | 49 +++++++++++++++++++++-----------------------
> >  qapi/block.json      | 29 +++++++++++++-------------
> >  qapi/migration.json  |  9 ++++----
> >  qapi/misc-arm.json   |  9 ++++----
> >  qapi/misc.json       | 13 ++++++------
> >  qapi/qdev.json       | 14 ++++++-------
> >  6 files changed, 58 insertions(+), 65 deletions(-)
> >
> > diff --git a/qapi/block-core.json b/qapi/block-core.json
> > index 1ca147285e7..c505369aeb2 100644
> > --- a/qapi/block-core.json
> > +++ b/qapi/block-core.json
> > @@ -1772,13 +1772,12 @@
> >
> >  ##
> >  # @blockdev-snapshot:
> > +#     Takes a snapshot of a block device.
> >  #
> > -# Takes a snapshot of a block device.
> > -#
> > -# Take a snapshot, by installing 'node' as the backing image of
> > -# 'overlay'.  Additionally, if 'node' is associated with a block
> > -# device, the block device changes to using 'overlay' as its new
> > -# active image.
> > +#     Take a snapshot, by installing 'node' as the backing image of
> > +#     'overlay'.  Additionally, if 'node' is associated with a block
> > +#     device, the block device changes to using 'overlay' as its new
> > +#     active image.
>
> 'overlay' and 'node' refer to arguments, so they should be @overlay and
> @node.  Since the arguments are in type BlockdevSnapshot, the reference
> is non-local until the inliner lands.

It isn't a reference at all as far as Sphinx is concerned, merely a
markup convention. Whether or not that convention applies to non-local
things is kind of up to you. If you say the word, I'll edit these in
this series and forward if you wish, but my default will be to leave
it alone.

>
> We may want to render this paragraph below the argument descriptions to
> avoid forward references.  This requires splitting it off the intro.  We
> can do it now, or leave it for later.
>
> Not splitting now keeps the conversion simple, which is a plus.  It
> reindents the entire unsplit intro, and if we do split it later, the
> part split off gets reindented right back.
>
> I'm leaning towards not rocking the boat, but you decide.

I'm likely to forget or ignore about later splits, so if it's
something you want, we may as well do it now. Note that we can just
decide to only indent the first paragraph and leave the second
unindented, and then it gets shifted into place during a later code
movement patch.

>
> Not noting these things again.
>
> >  #
> >  # Features:
> >  #
> > @@ -2471,15 +2470,15 @@
> >  ##
> >  # @block-dirty-bitmap-merge:
> >  #
>
> Drop the blank line.

ACK. Accidental remnants of adding a blank line intentionally to get
reflow to behave how I want.

>
> > -# Merge dirty bitmaps listed in @bitmaps to the @target dirty bitmap.
> > -# Dirty bitmaps in @bitmaps will be unchanged, except if it also
> > -# appears as the @target bitmap.  Any bits already set in @target will
> > -# still be set after the merge, i.e., this operation does not clear
> > -# the target.  On error, @target is unchanged.
> > +#     Merge dirty bitmaps listed in @bitmaps to the @target dirty
> > +#     bitmap.  Dirty bitmaps in @bitmaps will be unchanged, except if
> > +#     it also appears as the @target bitmap.  Any bits already set in
> > +#     @target will still be set after the merge, i.e., this operation
> > +#     does not clear the target.  On error, @target is unchanged.
> >  #
> > -# The resulting bitmap will count as dirty any clusters that were
> > -# dirty in any of the source bitmaps.  This can be used to achieve
> > -# backup checkpoints, or in simpler usages, to copy bitmaps.
> > +#     The resulting bitmap will count as dirty any clusters that were
> > +#     dirty in any of the source bitmaps.  This can be used to achieve
> > +#     backup checkpoints, or in simpler usages, to copy bitmaps.
> >  #
> >  # Errors:
> >  #     - If @node is not a valid block device, DeviceNotFound
> > @@ -5848,15 +5847,14 @@
> >
> >  ##
> >  # @block-set-write-threshold:
> > +#     Change the write threshold for a block drive.  An event will be
> > +#     delivered if a write to this block drive crosses the configured
> > +#     threshold.  The threshold is an offset, thus must be
> > +#     non-negative.  Default is no write threshold.  Setting the
> > +#     threshold to zero disables it.
> >  #
> > -# Change the write threshold for a block drive.  An event will be
> > -# delivered if a write to this block drive crosses the configured
> > -# threshold.  The threshold is an offset, thus must be non-negative.
> > -# Default is no write threshold.  Setting the threshold to zero
> > -# disables it.
> > -#
> > -# This is useful to transparently resize thin-provisioned drives
> > -# without the guest OS noticing.
> > +#     This is useful to transparently resize thin-provisioned drives
> > +#     without the guest OS noticing.
> >  #
> >  # @node-name: graph node name on which the threshold must be set.
> >  #
> > @@ -5938,11 +5936,10 @@
> >
> >  ##
> >  # @x-blockdev-set-iothread:
> > +#     Move @node and its children into the @iothread.  If @iothread is
> > +#     null then move @node and its children into the main loop.
> >  #
> > -# Move @node and its children into the @iothread.  If @iothread is
> > -# null then move @node and its children into the main loop.
> > -#
> > -# The node must not be attached to a BlockBackend.
> > +#     The node must not be attached to a BlockBackend.
>
> This one arguably lacks an intro.  Let's not worry about this now.

How about I indent *nothing* and lead with a "#TODO: This command
needs an introduction" ?

>
> >  #
> >  # @node-name: the name of the block driver node
> >  #
> > diff --git a/qapi/block.json b/qapi/block.json
> > index e47592d5500..15f08372564 100644
> > --- a/qapi/block.json
> > +++ b/qapi/block.json
> > @@ -181,12 +181,13 @@
> >
> >  ##
> >  # @blockdev-close-tray:
> > +#     Closes a block device's tray.
> >  #
> > -# Closes a block device's tray.  If there is a block driver state tree
> > -# associated with the block device (which is currently ejected), that
> > -# tree will be loaded as the medium.
> > +#     If there is a block driver state tree associated with the block
> > +#     device (which is currently ejected), that tree will be loaded as
> > +#     the medium.
> >  #
> > -# If the tray was already closed before, this will be a no-op.
> > +#     If the tray was already closed before, this will be a no-op.
> >  #
> >  # @device: Block device name
> >  #
>
> Shouldn't this one be in "[PATCH 5/9] qapi: split intro sections for
> commands"?

Ah, I did something halfway between ... Well, this particular block
doesn't actually add a new "split", but I did reflow the paragraphs
*as if* I had performed the split.

Let's collapse this one way or the other: please state your
preference, and I'll sift it into the correct patch.

>
> > @@ -218,13 +219,12 @@
> >
> >  ##
> >  # @blockdev-remove-medium:
> > +#     Removes a medium (a block driver state tree) from a block
> > +#     device.  That block device's tray must currently be open
> > +#     (unless there is no attached guest device).
> >  #
> > -# Removes a medium (a block driver state tree) from a block device.
> > -# That block device's tray must currently be open (unless there is no
> > -# attached guest device).
> > -#
> > -# If the tray is open and there is no medium inserted, this will be a
> > -# no-op.
> > +#     If the tray is open and there is no medium inserted, this will
> > +#     be a no-op.
> >  #
> >  # @id: The name or QOM path of the guest device
> >  #
> > @@ -504,12 +504,11 @@
> >
> >  ##
> >  # @block-latency-histogram-set:
> > +#     Manage read, write and flush latency histograms for the device.
> >  #
> > -# Manage read, write and flush latency histograms for the device.
> > -#
> > -# If only @id parameter is specified, remove all present latency
> > -# histograms for the device.  Otherwise, add/reset some of (or all)
> > -# latency histograms.
> > +#     If only @id parameter is specified, remove all present latency
> > +#     histograms for the device.  Otherwise, add/reset some of (or
> > +#     all) latency histograms.
> >  #
> >  # @id: The name or QOM path of the guest device.
> >  #
> > diff --git a/qapi/migration.json b/qapi/migration.json
> > index 8096ef64682..13c446b922f 100644
> > --- a/qapi/migration.json
> > +++ b/qapi/migration.json
> > @@ -1965,12 +1965,11 @@
> >
> >  ##
> >  # @cancel-vcpu-dirty-limit:
> > +#     Cancel the upper limit of dirty page rate for virtual CPUs.
> >  #
> > -# Cancel the upper limit of dirty page rate for virtual CPUs.
> > -#
> > -# Cancel the dirty page limit for the vCPU which has been set with
> > -# `set-vcpu-dirty-limit` command.  Note that this command requires
> > -# support from dirty ring, same as the `set-vcpu-dirty-limit`.
> > +#     Cancel the dirty page limit for the vCPU which has been set with
> > +#     `set-vcpu-dirty-limit` command.  Note that this command requires
> > +#     support from dirty ring, same as the `set-vcpu-dirty-limit`.
> >  #
> >  # @cpu-index: index of a virtual CPU, default is all.
> >  #
> > diff --git a/qapi/misc-arm.json b/qapi/misc-arm.json
> > index 8cb2ea77951..64059b5688d 100644
> > --- a/qapi/misc-arm.json
> > +++ b/qapi/misc-arm.json
> > @@ -28,12 +28,11 @@
> >
> >  ##
> >  # @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.
> > +#     On non-ARM targets this command will report an error as the GIC
> > +#     technology is not applicable.
> >  #
> >  # Since: 2.6
> >  #
> > diff --git a/qapi/misc.json b/qapi/misc.json
> > index b3c2a1421f3..374711ac6c7 100644
> > --- a/qapi/misc.json
> > +++ b/qapi/misc.json
> > @@ -178,14 +178,13 @@
> >
> >  ##
> >  # @x-exit-preconfig:
> > +#     Exit from "preconfig" state
> >  #
> > -# Exit from "preconfig" state
> > -#
> > -# This command makes QEMU exit the preconfig state and proceed with VM
> > -# initialization using configuration data provided on the command line
> > -# and via the QMP monitor during the preconfig state.  The command is
> > -# only available during the preconfig state (i.e. when the --preconfig
> > -# command line option was in use).
> > +#     This command makes QEMU exit the preconfig state and proceed
> > +#     with VM initialization using configuration data provided on the
> > +#     command line and via the QMP monitor during the preconfig state.
> > +#     The command is only available during the preconfig state
> > +#     (i.e. when the --preconfig command line option was in use).
> >  #
> >  # Features:
> >  #
> > diff --git a/qapi/qdev.json b/qapi/qdev.json
> > index a35321d2fd1..e19a92a44e8 100644
> > --- a/qapi/qdev.json
> > +++ b/qapi/qdev.json
> > @@ -163,14 +163,14 @@
> >  ##
> >  # @device-sync-config:
> >  #
>
> Drop the blank line.

ACK

>
> > -# Synchronize device configuration from host to guest part.  First,
> > -# copy the configuration from the host part (backend) to the guest
> > -# part (frontend).  Then notify guest software that device
> > -# configuration changed.
> > +#     Synchronize device configuration from host to guest part.
> > +#     First, copy the configuration from the host part (backend) to
> > +#     the guest part (frontend).  Then notify guest software that
> > +#     device configuration changed.
> >  #
> > -# The command may be used to notify the guest about block device
> > -# capacity change.  Currently only vhost-user-blk device supports
> > -# this.
> > +#     The command may be used to notify the guest about block device
> > +#     capacity change.  Currently only vhost-user-blk device supports
> > +#     this.
> >  #
> >  # @id: the device's ID or QOM path
> >  #
>

Re: [PATCH 2/9] qapi: convert multi-paragraph intros (commands)

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> On Wed, Sep 16, 2026 at 5:38 AM Markus Armbruster <armbru@redhat.com> wrote:
>>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > This patch converts some slightly-non-trivial intros with more than
>> > one paragraph, but doesn't create any new intro/details splits.
>> >
>> > Review notes: Some of these possibly could be split, but as they are commands
>> > (not eligible as an inlining source) and the additional information in
>> > the intro is not terribly long, I opted to leave them alone instead of
>> > laboring on prose rewrites.
>> >
>> > Signed-off-by: John Snow <jsnow@redhat.com>
>> > ---
>> >  qapi/block-core.json | 49 +++++++++++++++++++++-----------------------
>> >  qapi/block.json      | 29 +++++++++++++-------------
>> >  qapi/migration.json  |  9 ++++----
>> >  qapi/misc-arm.json   |  9 ++++----
>> >  qapi/misc.json       | 13 ++++++------
>> >  qapi/qdev.json       | 14 ++++++-------
>> >  6 files changed, 58 insertions(+), 65 deletions(-)
>> >
>> > diff --git a/qapi/block-core.json b/qapi/block-core.json
>> > index 1ca147285e7..c505369aeb2 100644
>> > --- a/qapi/block-core.json
>> > +++ b/qapi/block-core.json
>> > @@ -1772,13 +1772,12 @@
>> >
>> >  ##
>> >  # @blockdev-snapshot:
>> > +#     Takes a snapshot of a block device.
>> >  #
>> > -# Takes a snapshot of a block device.
>> > -#
>> > -# Take a snapshot, by installing 'node' as the backing image of
>> > -# 'overlay'.  Additionally, if 'node' is associated with a block
>> > -# device, the block device changes to using 'overlay' as its new
>> > -# active image.
>> > +#     Take a snapshot, by installing 'node' as the backing image of
>> > +#     'overlay'.  Additionally, if 'node' is associated with a block
>> > +#     device, the block device changes to using 'overlay' as its new
>> > +#     active image.
>>
>> 'overlay' and 'node' refer to arguments, so they should be @overlay and
>> @node.  Since the arguments are in type BlockdevSnapshot, the reference
>> is non-local until the inliner lands.
>
> It isn't a reference at all as far as Sphinx is concerned, merely a
> markup convention. Whether or not that convention applies to non-local
> things is kind of up to you. If you say the word, I'll edit these in
> this series and forward if you wish, but my default will be to leave
> it alone.

Right now, improving markup is a distraction we need to avoid.  We
should still take notes for later, though.

The obvious goal is to mark up references to things so they can be
suitably rendered, preferably as links.

Solved markup problem for references to definitions (`name-of-defn`) and
local member descriptions (@name-of-member).  We don't have a good
solution for referencing non-local member descriptions.

>> We may want to render this paragraph below the argument descriptions to
>> avoid forward references.  This requires splitting it off the intro.  We
>> can do it now, or leave it for later.
>>
>> Not splitting now keeps the conversion simple, which is a plus.  It
>> reindents the entire unsplit intro, and if we do split it later, the
>> part split off gets reindented right back.
>>
>> I'm leaning towards not rocking the boat, but you decide.
>
> I'm likely to forget or ignore about later splits, so if it's
> something you want, we may as well do it now. Note that we can just
> decide to only indent the first paragraph and leave the second
> unindented, and then it gets shifted into place during a later code
> movement patch.

Yes, that's splitting off the intro.  It forces us to revisit the doc
comment when we eliminate the plain sections between intro and tagged
sections.  Simple way to punt contents work down the road some.

I'm encouraging you to do that when you're less than sure the contents
should be intro, simply because the primary goal right now is to get the
syntax conversion done.  Limiting followup cleanup work is secondary: we
do it whenever it doesn't distract us from the primary.

Makes sense?

>> Not noting these things again.
>>
>> >  #
>> >  # Features:
>> >  #
>> > @@ -2471,15 +2470,15 @@
>> >  ##
>> >  # @block-dirty-bitmap-merge:
>> >  #
>>
>> Drop the blank line.
>
> ACK. Accidental remnants of adding a blank line intentionally to get
> reflow to behave how I want.
>
>>
>> > -# Merge dirty bitmaps listed in @bitmaps to the @target dirty bitmap.
>> > -# Dirty bitmaps in @bitmaps will be unchanged, except if it also
>> > -# appears as the @target bitmap.  Any bits already set in @target will
>> > -# still be set after the merge, i.e., this operation does not clear
>> > -# the target.  On error, @target is unchanged.
>> > +#     Merge dirty bitmaps listed in @bitmaps to the @target dirty
>> > +#     bitmap.  Dirty bitmaps in @bitmaps will be unchanged, except if
>> > +#     it also appears as the @target bitmap.  Any bits already set in
>> > +#     @target will still be set after the merge, i.e., this operation
>> > +#     does not clear the target.  On error, @target is unchanged.
>> >  #
>> > -# The resulting bitmap will count as dirty any clusters that were
>> > -# dirty in any of the source bitmaps.  This can be used to achieve
>> > -# backup checkpoints, or in simpler usages, to copy bitmaps.
>> > +#     The resulting bitmap will count as dirty any clusters that were
>> > +#     dirty in any of the source bitmaps.  This can be used to achieve
>> > +#     backup checkpoints, or in simpler usages, to copy bitmaps.
>> >  #
>> >  # Errors:
>> >  #     - If @node is not a valid block device, DeviceNotFound
>> > @@ -5848,15 +5847,14 @@
>> >
>> >  ##
>> >  # @block-set-write-threshold:
>> > +#     Change the write threshold for a block drive.  An event will be
>> > +#     delivered if a write to this block drive crosses the configured
>> > +#     threshold.  The threshold is an offset, thus must be
>> > +#     non-negative.  Default is no write threshold.  Setting the
>> > +#     threshold to zero disables it.
>> >  #
>> > -# Change the write threshold for a block drive.  An event will be
>> > -# delivered if a write to this block drive crosses the configured
>> > -# threshold.  The threshold is an offset, thus must be non-negative.
>> > -# Default is no write threshold.  Setting the threshold to zero
>> > -# disables it.
>> > -#
>> > -# This is useful to transparently resize thin-provisioned drives
>> > -# without the guest OS noticing.
>> > +#     This is useful to transparently resize thin-provisioned drives
>> > +#     without the guest OS noticing.
>> >  #
>> >  # @node-name: graph node name on which the threshold must be set.
>> >  #
>> > @@ -5938,11 +5936,10 @@
>> >
>> >  ##
>> >  # @x-blockdev-set-iothread:
>> > +#     Move @node and its children into the @iothread.  If @iothread is
>> > +#     null then move @node and its children into the main loop.
>> >  #
>> > -# Move @node and its children into the @iothread.  If @iothread is
>> > -# null then move @node and its children into the main loop.
>> > -#
>> > -# The node must not be attached to a BlockBackend.
>> > +#     The node must not be attached to a BlockBackend.
>>
>> This one arguably lacks an intro.  Let's not worry about this now.
>
> How about I indent *nothing* and lead with a "#TODO: This command
> needs an introduction" ?

Do we want every command to have an intro?

If we do, we should enforce it at some point.  If we plan to enforce it,
simply leaving the intro empty now will be caught without a TODO.

I'm taking note:

9. Consider making intro mandatory (maybe just for commands and
events?)

>> >  #
>> >  # @node-name: the name of the block driver node
>> >  #
>> > diff --git a/qapi/block.json b/qapi/block.json
>> > index e47592d5500..15f08372564 100644
>> > --- a/qapi/block.json
>> > +++ b/qapi/block.json
>> > @@ -181,12 +181,13 @@
>> >
>> >  ##
>> >  # @blockdev-close-tray:
>> > +#     Closes a block device's tray.
>> >  #
>> > -# Closes a block device's tray.  If there is a block driver state tree
>> > -# associated with the block device (which is currently ejected), that
>> > -# tree will be loaded as the medium.
>> > +#     If there is a block driver state tree associated with the block
>> > +#     device (which is currently ejected), that tree will be loaded as
>> > +#     the medium.
>> >  #
>> > -# If the tray was already closed before, this will be a no-op.
>> > +#     If the tray was already closed before, this will be a no-op.
>> >  #
>> >  # @device: Block device name
>> >  #
>>
>> Shouldn't this one be in "[PATCH 5/9] qapi: split intro sections for
>> commands"?
>
> Ah, I did something halfway between ... Well, this particular block
> doesn't actually add a new "split", but I did reflow the paragraphs
> *as if* I had performed the split.

You're right.

> Let's collapse this one way or the other: please state your
> preference, and I'll sift it into the correct patch.

Breaking the paragraph like you did feels like an improvement to me.

If we think the contents after the paragraph split should not be intro,
then the adjusted patch should be in "[PATCH 5/9] qapi: split intro
sections for commands".

If we think keeping it in intro is fine, then it should stay here.
However, the paragraph split is an unnecesseary contents improvement
then.  Better to keep the syntax conversion patches focused to ease
review.

I'm leaning towards the latter.  Thus:

   ##
   # @blockdev-close-tray:
  -#
  -# Closes a block device's tray.  If there is a block driver state tree
  -# associated with the block device (which is currently ejected), that
  -# tree will be loaded as the medium.
  -#
  -# If the tray was already closed before, this will be a no-op.
  +#     Closes a block device's tray.  If there is a block driver state
  +#     tree associated with the block device (which is currently
  +#     ejected), that tree will be loaded as the medium.
  +#     
  +#     If the tray was already closed before, this will be a no-op.
   #
   # @device: Block device name
   #

Thoughts?

[...]

[PATCH 3/9] qapi: convert multi-paragraph intros (enums)

[John Snow]

This patch converts some slightly-non-trivial intros with more than
one paragraph, but doesn't create any new intro/details splits.

Review notes: The "See also ..." texts here are prime candidates for
moving into the details section with a ".. seealso::", but like the
last patch, as these are for enums and not candidates as an inline
source, I left them alone for now to keep patch sizes and motion down
until after initial review.

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

diff --git a/qapi/machine.json b/qapi/machine.json
index 0516112f8e8..710b638b3bf 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -608,12 +608,12 @@
 
 ##
 # @HmatLBMemoryHierarchy:
+#     The memory hierarchy in the System Locality Latency and
+#     Bandwidth Information Structure of HMAT (Heterogeneous Memory
+#     Attribute Table)
 #
-# The memory hierarchy in the System Locality Latency and Bandwidth
-# Information Structure of HMAT (Heterogeneous Memory Attribute Table)
-#
-# For more information about `HmatLBMemoryHierarchy`, see chapter
-# 5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec.
+#     For more information about `HmatLBMemoryHierarchy`, see chapter
+#     5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec.
 #
 # @memory: the structure represents the memory performance
 #
@@ -630,12 +630,12 @@
 
 ##
 # @HmatLBDataType:
+#     Data type in the System Locality Latency and Bandwidth
+#     Information Structure of HMAT (Heterogeneous Memory Attribute
+#     Table)
 #
-# Data type in the System Locality Latency and Bandwidth Information
-# Structure of HMAT (Heterogeneous Memory Attribute Table)
-#
-# For more information about `HmatLBDataType`, see chapter 5.2.27.4:
-# Table 5-146: Field "Data Type" of ACPI 6.3 spec.
+#     For more information about `HmatLBDataType`, see chapter
+#     5.2.27.4: Table 5-146: Field "Data Type" of ACPI 6.3 spec.
 #
 # @access-latency: access latency (nanoseconds)
 #
@@ -693,12 +693,11 @@
 
 ##
 # @HmatCacheAssociativity:
+#     Cache associativity in the Memory Side Cache Information
+#     Structure of HMAT
 #
-# Cache associativity in the Memory Side Cache Information Structure
-# of HMAT
-#
-# For more information of `HmatCacheAssociativity`, see chapter
-# 5.2.27.5: Table 5-147 of ACPI 6.3 spec.
+#     For more information of `HmatCacheAssociativity`, see chapter
+#     5.2.27.5: Table 5-147 of ACPI 6.3 spec.
 #
 # @none: None (no memory side cache in this proximity domain, or cache
 #     associativity unknown)
@@ -714,12 +713,12 @@
 
 ##
 # @HmatCacheWritePolicy:
+#     Cache write policy in the Memory Side Cache Information
+#     Structure of HMAT
 #
-# Cache write policy in the Memory Side Cache Information Structure of
-# HMAT
-#
-# For more information of `HmatCacheWritePolicy`, see chapter
-# 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
+#     For more information of `HmatCacheWritePolicy`, see chapter
+#     5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3
+#     spec.
 #
 # @none: None (no memory side cache in this proximity domain, or cache
 #     write policy unknown)
-- 
2.55.0

Re: [PATCH 3/9] qapi: convert multi-paragraph intros (enums)

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> This patch converts some slightly-non-trivial intros with more than
> one paragraph, but doesn't create any new intro/details splits.
>
> Review notes: The "See also ..." texts here are prime candidates for
> moving into the details section with a ".. seealso::", but like the
> last patch, as these are for enums and not candidates as an inline
> source, I left them alone for now to keep patch sizes and motion down
> until after initial review.
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/machine.json | 39 +++++++++++++++++++--------------------
>  1 file changed, 19 insertions(+), 20 deletions(-)
>
> diff --git a/qapi/machine.json b/qapi/machine.json
> index 0516112f8e8..710b638b3bf 100644
> --- a/qapi/machine.json
> +++ b/qapi/machine.json
> @@ -608,12 +608,12 @@
>  
>  ##
>  # @HmatLBMemoryHierarchy:
> +#     The memory hierarchy in the System Locality Latency and
> +#     Bandwidth Information Structure of HMAT (Heterogeneous Memory
> +#     Attribute Table)
>  #
> -# The memory hierarchy in the System Locality Latency and Bandwidth
> -# Information Structure of HMAT (Heterogeneous Memory Attribute Table)
> -#
> -# For more information about `HmatLBMemoryHierarchy`, see chapter
> -# 5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec.
> +#     For more information about `HmatLBMemoryHierarchy`, see chapter
> +#     5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec.

This is one of the "see also" you discussed in the commit message.  Such
references tend to belong closer to the end, not in the intro.  Moving
involves a split.

More of the same below.

Not splitting now keeps the conversion simple, which is a plus.  It
reindents the entire unsplit intro, and if we do split it later, the
part split off gets reindented right back.

I'm happy to leave this decision to you.  I'm adding to my notes on
future work:

8. Move "see also" out of intro

>  #
>  # @memory: the structure represents the memory performance
>  #
> @@ -630,12 +630,12 @@
>  
>  ##
>  # @HmatLBDataType:
> +#     Data type in the System Locality Latency and Bandwidth
> +#     Information Structure of HMAT (Heterogeneous Memory Attribute
> +#     Table)
>  #
> -# Data type in the System Locality Latency and Bandwidth Information
> -# Structure of HMAT (Heterogeneous Memory Attribute Table)
> -#
> -# For more information about `HmatLBDataType`, see chapter 5.2.27.4:
> -# Table 5-146: Field "Data Type" of ACPI 6.3 spec.
> +#     For more information about `HmatLBDataType`, see chapter
> +#     5.2.27.4: Table 5-146: Field "Data Type" of ACPI 6.3 spec.
>  #
>  # @access-latency: access latency (nanoseconds)
>  #
> @@ -693,12 +693,11 @@
>  
>  ##
>  # @HmatCacheAssociativity:
> +#     Cache associativity in the Memory Side Cache Information
> +#     Structure of HMAT
>  #
> -# Cache associativity in the Memory Side Cache Information Structure
> -# of HMAT
> -#
> -# For more information of `HmatCacheAssociativity`, see chapter
> -# 5.2.27.5: Table 5-147 of ACPI 6.3 spec.
> +#     For more information of `HmatCacheAssociativity`, see chapter
> +#     5.2.27.5: Table 5-147 of ACPI 6.3 spec.
>  #
>  # @none: None (no memory side cache in this proximity domain, or cache
>  #     associativity unknown)
> @@ -714,12 +713,12 @@
>  
>  ##
>  # @HmatCacheWritePolicy:
> +#     Cache write policy in the Memory Side Cache Information
> +#     Structure of HMAT
>  #
> -# Cache write policy in the Memory Side Cache Information Structure of
> -# HMAT
> -#
> -# For more information of `HmatCacheWritePolicy`, see chapter
> -# 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
> +#     For more information of `HmatCacheWritePolicy`, see chapter
> +#     5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3
> +#     spec.
>  #
>  # @none: None (no memory side cache in this proximity domain, or cache
>  #     write policy unknown)

Re: [PATCH 3/9] qapi: convert multi-paragraph intros (enums)

[John Snow]

On Wed, Sep 16, 2026 at 5:47 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> John Snow <jsnow@redhat.com> writes:
>
> > This patch converts some slightly-non-trivial intros with more than
> > one paragraph, but doesn't create any new intro/details splits.
> >
> > Review notes: The "See also ..." texts here are prime candidates for
> > moving into the details section with a ".. seealso::", but like the
> > last patch, as these are for enums and not candidates as an inline
> > source, I left them alone for now to keep patch sizes and motion down
> > until after initial review.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> >  qapi/machine.json | 39 +++++++++++++++++++--------------------
> >  1 file changed, 19 insertions(+), 20 deletions(-)
> >
> > diff --git a/qapi/machine.json b/qapi/machine.json
> > index 0516112f8e8..710b638b3bf 100644
> > --- a/qapi/machine.json
> > +++ b/qapi/machine.json
> > @@ -608,12 +608,12 @@
> >
> >  ##
> >  # @HmatLBMemoryHierarchy:
> > +#     The memory hierarchy in the System Locality Latency and
> > +#     Bandwidth Information Structure of HMAT (Heterogeneous Memory
> > +#     Attribute Table)
> >  #
> > -# The memory hierarchy in the System Locality Latency and Bandwidth
> > -# Information Structure of HMAT (Heterogeneous Memory Attribute Table)
> > -#
> > -# For more information about `HmatLBMemoryHierarchy`, see chapter
> > -# 5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec.
> > +#     For more information about `HmatLBMemoryHierarchy`, see chapter
> > +#     5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec.
>
> This is one of the "see also" you discussed in the commit message.  Such
> references tend to belong closer to the end, not in the intro.  Moving
> involves a split.
>
> More of the same below.
>
> Not splitting now keeps the conversion simple, which is a plus.  It
> reindents the entire unsplit intro, and if we do split it later, the
> part split off gets reindented right back.
>
> I'm happy to leave this decision to you.  I'm adding to my notes on
> future work:
>
> 8. Move "see also" out of intro
>

If you believe the ultimate destination for these is below the fold,
I'm happy to do it now. I just *didn't* because I wasn't entirely
sure. If you are, let's get it over with.

Re: [PATCH 3/9] qapi: convert multi-paragraph intros (enums)

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> On Wed, Sep 16, 2026 at 5:47 AM Markus Armbruster <armbru@redhat.com> wrote:
>>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > This patch converts some slightly-non-trivial intros with more than
>> > one paragraph, but doesn't create any new intro/details splits.
>> >
>> > Review notes: The "See also ..." texts here are prime candidates for
>> > moving into the details section with a ".. seealso::", but like the
>> > last patch, as these are for enums and not candidates as an inline
>> > source, I left them alone for now to keep patch sizes and motion down
>> > until after initial review.
>> >
>> > Signed-off-by: John Snow <jsnow@redhat.com>
>> > ---
>> >  qapi/machine.json | 39 +++++++++++++++++++--------------------
>> >  1 file changed, 19 insertions(+), 20 deletions(-)
>> >
>> > diff --git a/qapi/machine.json b/qapi/machine.json
>> > index 0516112f8e8..710b638b3bf 100644
>> > --- a/qapi/machine.json
>> > +++ b/qapi/machine.json
>> > @@ -608,12 +608,12 @@
>> >
>> >  ##
>> >  # @HmatLBMemoryHierarchy:
>> > +#     The memory hierarchy in the System Locality Latency and
>> > +#     Bandwidth Information Structure of HMAT (Heterogeneous Memory
>> > +#     Attribute Table)
>> >  #
>> > -# The memory hierarchy in the System Locality Latency and Bandwidth
>> > -# Information Structure of HMAT (Heterogeneous Memory Attribute Table)
>> > -#
>> > -# For more information about `HmatLBMemoryHierarchy`, see chapter
>> > -# 5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec.
>> > +#     For more information about `HmatLBMemoryHierarchy`, see chapter
>> > +#     5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec.
>>
>> This is one of the "see also" you discussed in the commit message.  Such
>> references tend to belong closer to the end, not in the intro.  Moving
>> involves a split.
>>
>> More of the same below.
>>
>> Not splitting now keeps the conversion simple, which is a plus.  It
>> reindents the entire unsplit intro, and if we do split it later, the
>> part split off gets reindented right back.
>>
>> I'm happy to leave this decision to you.  I'm adding to my notes on
>> future work:
>>
>> 8. Move "see also" out of intro
>>
>
> If you believe the ultimate destination for these is below the fold,
> I'm happy to do it now. I just *didn't* because I wasn't entirely
> sure. If you are, let's get it over with.

Having thought some more to reply to 2/9, I'd now draw the boundary like
this: if we believe the ultimate destination is above the fold, make it
intro, else keep it plain.

This kicks less than easy contents decisions down the road to "eliminate
plain sections after intro".

Right now we need to get the syntax conversion done and merged.  Doing
plain section elimination incrementally is less bad than doing syntax
conversion incrementally, I believe.

Makes sense?

[PATCH 4/9] qapi: convert multi-paragraph intros (structs)

[John Snow]

This patch converts some slightly-non-trivial intros with more than
one paragraph, but doesn't create any new intro/details splits.

Review notes: Again, the Numa Hmat options have text that are prime
candidates for a ".. seealso::" admonition, but I was uncertain as to
whether this information was principally for developers or for
users. If it's for developers, it can stay in the intro where it will
be dropped when inlined. If it is for users, they should be moved into
the details region.

The remaining structs have an awful lot of text, but I was not
immediately sure of which information we wanted to preserve when
inlined or not; these structures tend to be written as if they are
describing a command, but they actually only define a set of
arguments.

Advice? Opinions?

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/machine.json | 17 ++++++++---------
 qapi/net.json     | 34 +++++++++++++++-------------------
 qapi/qom.json     | 18 +++++++++---------
 3 files changed, 32 insertions(+), 37 deletions(-)

diff --git a/qapi/machine.json b/qapi/machine.json
index 710b638b3bf..aaecd151407 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -657,12 +657,11 @@
 
 ##
 # @NumaHmatLBOptions:
+#     Set the system locality latency and bandwidth information
+#     between Initiator and Target proximity Domains.
 #
-# Set the system locality latency and bandwidth information between
-# Initiator and Target proximity Domains.
-#
-# For more information about `NumaHmatLBOptions`, see chapter
-# 5.2.27.4: Table 5-146 of ACPI 6.3 spec.
+#     For more information about `NumaHmatLBOptions`, see chapter
+#     5.2.27.4: Table 5-146 of ACPI 6.3 spec.
 #
 # @initiator: the Initiator Proximity Domain.
 #
@@ -734,11 +733,11 @@
 
 ##
 # @NumaHmatCacheOptions:
+#     Set the memory side cache information for a given memory domain.
 #
-# Set the memory side cache information for a given memory domain.
-#
-# For more information of `NumaHmatCacheOptions`, see chapter
-# 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
+#     For more information of `NumaHmatCacheOptions`, see chapter
+#     5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3
+#     spec.
 #
 # @node-id: the memory proximity domain to which the memory belongs.
 #
diff --git a/qapi/net.json b/qapi/net.json
index 7aabd8b9260..50dc3137182 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -681,11 +681,10 @@
 
 ##
 # @NetdevVhostVDPAOptions:
+#     Vhost-vdpa network backend
 #
-# Vhost-vdpa network backend
-#
-# vDPA device is a device that uses a datapath which complies with the
-# virtio specifications with a vendor specific control path.
+#     vDPA device is a device that uses a datapath which complies with
+#     the virtio specifications with a vendor specific control path.
 #
 # @vhostdev: path of vhost-vdpa device (default:'/dev/vhost-vdpa-0')
 #
@@ -712,11 +711,10 @@
 
 ##
 # @NetdevVmnetHostOptions:
+#     vmnet (host mode) network backend.
 #
-# vmnet (host mode) network backend.
-#
-# Allows the vmnet interface to communicate with other vmnet
-# interfaces that are in host mode and also with the host.
+#     Allows the vmnet interface to communicate with other vmnet
+#     interfaces that are in host mode and also with the host.
 #
 # @start-address: The starting IPv4 address to use for the interface.
 #     Must be in the private IP range (RFC 1918).  Must be specified
@@ -755,15 +753,14 @@
 
 ##
 # @NetdevVmnetSharedOptions:
+#     vmnet (shared mode) network backend.
 #
-# vmnet (shared mode) network backend.
-#
-# Allows traffic originating from the vmnet interface to reach the
-# Internet through a network address translator (NAT).  The vmnet
-# interface can communicate with the host and with other shared mode
-# interfaces on the same subnet.  If no DHCP settings, subnet mask and
-# IPv6 prefix specified, the interface can communicate with any of
-# other interfaces in shared mode.
+#     Allows traffic originating from the vmnet interface to reach the
+#     Internet through a network address translator (NAT).  The vmnet
+#     interface can communicate with the host and with other shared
+#     mode interfaces on the same subnet.  If no DHCP settings, subnet
+#     mask and IPv6 prefix specified, the interface can communicate
+#     with any of other interfaces in shared mode.
 #
 # @start-address: The starting IPv4 address to use for the interface.
 #     Must be in the private IP range (RFC 1918).  Must be specified
@@ -800,10 +797,9 @@
 
 ##
 # @NetdevVmnetBridgedOptions:
+#     vmnet (bridged mode) network backend.
 #
-# vmnet (bridged mode) network backend.
-#
-# Bridges the vmnet interface with a physical network interface.
+#     Bridges the vmnet interface with a physical network interface.
 #
 # @ifname: The name of the physical interface to be bridged.
 #
diff --git a/qapi/qom.json b/qapi/qom.json
index 51af9485e6d..3de06488768 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -1033,16 +1033,16 @@
 
 ##
 # @SevSnpGuestProperties:
+#     Properties for sev-snp-guest objects.  Most of these are direct
+#     arguments for the KVM_SNP_* interfaces documented in the Linux
+#     kernel source under
+#     Documentation/arch/x86/amd-memory-encryption.rst, which are in
+#     turn closely coupled with the SNP_INIT/SNP_LAUNCH_* firmware
+#     commands documented in the SEV-SNP Firmware ABI Specification
+#     (Rev 0.9).
 #
-# Properties for sev-snp-guest objects.  Most of these are direct
-# arguments for the KVM_SNP_* interfaces documented in the Linux
-# kernel source under
-# Documentation/arch/x86/amd-memory-encryption.rst, which are in turn
-# closely coupled with the SNP_INIT/SNP_LAUNCH_* firmware commands
-# documented in the SEV-SNP Firmware ABI Specification (Rev 0.9).
-#
-# More usage information is also available in the QEMU source tree
-# under docs/amd-memory-encryption.
+#     More usage information is also available in the QEMU source tree
+#     under docs/amd-memory-encryption.
 #
 # @policy: the 'POLICY' parameter to the SNP_LAUNCH_START command, as
 #     defined in the SEV-SNP firmware ABI (default: 0x30000)
-- 
2.55.0

Re: [PATCH 4/9] qapi: convert multi-paragraph intros (structs)

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> This patch converts some slightly-non-trivial intros with more than
> one paragraph, but doesn't create any new intro/details splits.
>
> Review notes: Again, the Numa Hmat options have text that are prime
> candidates for a ".. seealso::" admonition, but I was uncertain as to
> whether this information was principally for developers or for
> users. If it's for developers, it can stay in the intro where it will
> be dropped when inlined. If it is for users, they should be moved into
> the details region.

I think it's for users.

If I remember correctly, I complained in review that member descriptions
are greek for the uninitiated like myself.  The submitter pointed out
that explaining them would involve duplicating much of the relevant spec
document, so we agreed on adding a reference to that.

> The remaining structs have an awful lot of text, but I was not
> immediately sure of which information we wanted to preserve when
> inlined or not; these structures tend to be written as if they are
> describing a command, but they actually only define a set of
> arguments.
>
> Advice? Opinions?

When you're not sure whether certain contents is "intro" or "details",
leave it in "plain", because "plain" we'll revisit for sure.  Makes
sense?

> Signed-off-by: John Snow <jsnow@redhat.com>

[PATCH 5/9] qapi: split intro sections for commands

[John Snow]

For commands, the primary difference between "intro" and "details" is
that the intro will appear "above the fold" on generated HTML
documentation (i.e. before argument/features tables), and "details"
will appear afterwards.

Review notes: As these are commands, the split is more
arbitrary. These commands all have quite a bit of text, so I tended to
split off just the first sentence or maybe the first paragraph. Some
of these are likely candidates for writing a new one-sentence synopsis
and shuffling most, if not all, of the existing prose down into the
details.

As an artifact from when these patches were part of a much, much
larger set of changes, the details split is not physically relocated
in these patches to keep the diffs simple and obvious to read. This
can be changed if desired, but it does produce uglier diffs and can
obscure prose changes where they arise.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/block-core.json   | 76 ++++++++++++++++++------------------------
 qapi/block-export.json |  3 +-
 qapi/block.json        | 42 +++++++++++------------
 qapi/control.json      |  3 +-
 qapi/introspect.json   | 16 ++++-----
 qapi/job.json          | 43 +++++++++++-------------
 qapi/machine.json      | 30 ++++++++---------
 qapi/migration.json    |  9 +++--
 qapi/misc-i386.json    | 22 +++++-------
 qapi/misc.json         |  5 ++-
 qapi/net.json          |  3 +-
 qapi/stats.json        |  5 ++-
 qapi/transaction.json  |  6 ++--
 qapi/ui.json           |  3 +-
 14 files changed, 118 insertions(+), 148 deletions(-)

diff --git a/qapi/block-core.json b/qapi/block-core.json
index c505369aeb2..ec052f6bd2d 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1516,8 +1516,7 @@
 
 ##
 # @block_resize:
-#
-# Resize a block image while a guest is running.
+#     Resize a block image while a guest is running.
 #
 # Either @device or @node-name must be set but not both.
 #
@@ -1842,9 +1841,8 @@
 
 ##
 # @block-commit:
-#
-# Live commit of data from overlay image nodes into backing nodes -
-# i.e., writes data between 'top' and 'base' into 'base'.
+#     Live commit of data from overlay image nodes into backing nodes
+#     - i.e., writes data between 'top' and 'base' into 'base'.
 #
 # If top == base, that is an error.  If top has no overlays on top of
 # it, or if it is in use by a writer, the job will not be completed by
@@ -2824,8 +2822,7 @@
 
 ##
 # @block-stream:
-#
-# Copy data from a backing file into a block device.
+#     Copy data from a backing file into a block device.
 #
 # The block streaming operation is performed in the background until
 # the entire backing file has been copied.  This command returns
@@ -2936,8 +2933,7 @@
 
 ##
 # @block-job-set-speed:
-#
-# Set maximum speed for a background block operation.
+#     Set maximum speed for a background block operation.
 #
 # This command can only be issued when there is an active block job.
 #
@@ -2962,8 +2958,7 @@
 
 ##
 # @block-job-cancel:
-#
-# Stop an active background block operation.
+#     Stop an active background block operation.
 #
 # This command returns immediately after marking the active background
 # block operation for cancellation.  It is an error to call this
@@ -3005,8 +3000,7 @@
 
 ##
 # @block-job-pause:
-#
-# Pause an active background block operation.
+#     Pause an active background block operation.
 #
 # This command returns immediately after marking the active job for
 # pausing.  Pausing an already paused job is an error.
@@ -3038,8 +3032,7 @@
 
 ##
 # @block-job-resume:
-#
-# Resume an active background block operation.
+#     Resume an active background block operation.
 #
 # This command returns immediately after resuming a paused job.
 # Resuming an already running job is an error.
@@ -3067,9 +3060,9 @@
 
 ##
 # @block-job-complete:
-#
-# Manually trigger completion of an active job in the READY or STANDBY
-# state.  Completing the job in any other state is an error.
+#     Manually trigger completion of an active job in the READY or
+#     STANDBY state.  Completing the job in any other state is an
+#     error.
 #
 # This is supported only for drive mirroring, where it also switches
 # the device to write to the target path only.  Note that drive
@@ -3107,14 +3100,13 @@
 
 ##
 # @block-job-dismiss:
-#
-# Deletes a job that is in the CONCLUDED state.  This command only
-# needs to be run explicitly for jobs that don't have automatic
-# dismiss enabled.  In turn, automatic dismiss may be enabled only for
-# jobs that have @auto-dismiss option, which are `drive-backup`,
-# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit`
-# and `block-stream`.  @auto-dismiss is enabled by default for these
-# jobs.
+#     Deletes a job that is in the CONCLUDED state.  This command only
+#     needs to be run explicitly for jobs that don't have automatic
+#     dismiss enabled.  In turn, automatic dismiss may be enabled only
+#     for jobs that have @auto-dismiss option, which are
+#     `drive-backup`, `blockdev-backup`, `drive-mirror`,
+#     `blockdev-mirror`, `block-commit` and `block-stream`.
+#     @auto-dismiss is enabled by default for these jobs.
 #
 # This command will refuse to operate on any job that has not yet
 # reached its terminal state, CONCLUDED.  For jobs that make use of
@@ -3136,11 +3128,10 @@
 
 ##
 # @block-job-finalize:
-#
-# Instructs all jobs in a transaction (or a single job if it is not
-# part of any transaction) to finalize any graph changes and do any
-# necessary cleanup.  This command requires that all involved jobs are
-# in the PENDING state.
+#     Instructs all jobs in a transaction (or a single job if it is
+#     not part of any transaction) to finalize any graph changes and
+#     do any necessary cleanup.  This command requires that all
+#     involved jobs are in the PENDING state.
 #
 # For jobs in a transaction, instructing one job to finalize will
 # force ALL jobs in the transaction to finalize, so it is only
@@ -4882,14 +4873,13 @@
 
 ##
 # @blockdev-reopen:
-#
-# Reopens one or more block devices using the given set of options.
-# Any option not specified will be reset to its default value
-# regardless of its previous status.  If an option cannot be changed
-# or a particular driver does not support reopening then the command
-# will return an error.  All devices in the list are reopened in one
-# transaction, so if one of them fails then the whole transaction is
-# cancelled.
+#     Reopens one or more block devices using the given set of
+#     options.  Any option not specified will be reset to its default
+#     value regardless of its previous status.  If an option cannot be
+#     changed or a particular driver does not support reopening then
+#     the command will return an error.  All devices in the list are
+#     reopened in one transaction, so if one of them fails then the
+#     whole transaction is cancelled.
 #
 # The command receives a list of block devices to reopen.  For each
 # one of them, the top-level @node-name option (from
@@ -4961,9 +4951,8 @@
 
 ##
 # @blockdev-set-active:
-#
-# Activate or deactivate a block device.  Use this to manage the
-# handover of block devices on migration with qemu-storage-daemon.
+#     Activate or deactivate a block device.  Use this to manage the
+#     handover of block devices on migration with qemu-storage-daemon.
 #
 # Activating a node automatically activates all of its child nodes
 # first.  Deactivating a node automatically deactivates any of its
@@ -5876,8 +5865,7 @@
 
 ##
 # @x-blockdev-change:
-#
-# Dynamically reconfigure the block driver state graph.
+#     Dynamically reconfigure the block driver state graph.
 #
 # Currently only supports adding and deleting quorum children.  A
 # child will be added at the end of the list of children.  Its
diff --git a/qapi/block-export.json b/qapi/block-export.json
index e9f7e72c8ee..77459f6321b 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -235,8 +235,7 @@
 
 ##
 # @nbd-server-add:
-#
-# Export a block node to QEMU's embedded NBD server.
+#     Export a block node to QEMU's embedded NBD server.
 #
 # The export name will be used as the id for the resulting block
 # export.
diff --git a/qapi/block.json b/qapi/block.json
index 15f08372564..73aad7f4f2b 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -128,11 +128,25 @@
 
 ##
 # @blockdev-open-tray:
+#     Opens a block device's tray.
 #
-# Opens a block device's tray.  If there is a block driver state tree
-# inserted as a medium, it will become inaccessible to the guest (but
-# it will remain associated to the block device, so closing the tray
-# will make it accessible again).
+# @device: Block device name
+#
+# @id: The name or QOM path of the guest device (since: 2.8)
+#
+# @force: if false (the default), an eject request will be sent to the
+#     guest if it has locked the tray (and the tray will not be opened
+#     immediately); if true, the tray will be opened regardless of
+#     whether it is locked
+#
+# Features:
+#
+# @deprecated: Member @device is deprecated.  Use @id instead.
+#
+# If there is a block driver state tree inserted as a medium, it will
+# become inaccessible to the guest (but it will remain associated to
+# the block device, so closing the tray will make it accessible
+# again).
 #
 # If the tray was already open before, this will be a no-op.
 #
@@ -145,19 +159,6 @@
 #   device attached to it
 # - if the guest device does not have an actual tray
 #
-# @device: Block device name
-#
-# @id: The name or QOM path of the guest device (since: 2.8)
-#
-# @force: if false (the default), an eject request will be sent to the
-#     guest if it has locked the tray (and the tray will not be opened
-#     immediately); if true, the tray will be opened regardless of
-#     whether it is locked
-#
-# Features:
-#
-# @deprecated: Member @device is deprecated.  Use @id instead.
-#
 # Since: 2.5
 #
 # .. qmp-example::
@@ -429,8 +430,10 @@
 
 ##
 # @block_set_io_throttle:
+#     Change I/O throttle limits for a block drive.
 #
-# Change I/O throttle limits for a block drive.
+# Errors:
+#     - If @device is not a valid block device, DeviceNotFound
 #
 # Since QEMU 2.4, each device with I/O limits is member of a throttle
 # group.
@@ -453,9 +456,6 @@
 # case the device will be removed from its group and the rest of its
 # members will not be affected.  The 'group' parameter is ignored.
 #
-# Errors:
-#     - If @device is not a valid block device, DeviceNotFound
-#
 # Since: 1.1
 #
 # .. qmp-example::
diff --git a/qapi/control.json b/qapi/control.json
index 0fc465936d8..b19ca910d5f 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -152,8 +152,7 @@
 
 ##
 # @quit:
-#
-# Request graceful QEMU process termination.
+#     Request graceful QEMU process termination.
 #
 # While every attempt is made to send the QMP response before
 # terminating, this is not guaranteed.  When using this interface, a
diff --git a/qapi/introspect.json b/qapi/introspect.json
index bd42aac3358..d579e5c8554 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -17,15 +17,15 @@
 
 ##
 # @query-qmp-schema:
+#     Command `query-qmp-schema` exposes the QMP wire ABI as an array
+#     of `SchemaInfo`.  This lets QMP clients figure out what commands
+#     and events are available in this QEMU, and their parameters and
+#     results.
 #
-# Command `query-qmp-schema` exposes the QMP wire ABI as an array of
-# `SchemaInfo`.  This lets QMP clients figure out what commands and
-# events are available in this QEMU, and their parameters and results.
-#
-# However, the `SchemaInfo` can't reflect all the rules and
-# restrictions that apply to QMP.  It's interface introspection
-# (figuring out what's there), not interface specification.  The
-# specification is in the QAPI schema.
+# The `SchemaInfo` can't reflect all the rules and restrictions that
+# apply to QMP.  It's interface introspection (figuring out what's
+# there), not interface specification.  The specification is in the
+# QAPI schema.
 #
 # Furthermore, while we strive to keep the QMP wire format
 # backwards-compatible across QEMU versions, the introspection output
diff --git a/qapi/job.json b/qapi/job.json
index b68d7292423..1aec4ceb9f1 100644
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -128,8 +128,7 @@
 
 ##
 # @job-pause:
-#
-# Pause an active job.
+#     Pause an active job.
 #
 # This command returns immediately after marking the active job for
 # pausing.  Pausing an already paused job is an error.
@@ -148,8 +147,7 @@
 
 ##
 # @job-resume:
-#
-# Resume a paused job.
+#     Resume a paused job.
 #
 # This command returns immediately after resuming a paused job.
 # Resuming an already running job is an error.
@@ -165,10 +163,9 @@
 
 ##
 # @job-cancel:
-#
-# Instruct an active background job to cancel at the next opportunity.
-# This command returns immediately after marking the active job for
-# cancellation.
+#     Instruct an active background job to cancel at the next
+#     opportunity.  This command returns immediately after marking the
+#     active job for cancellation.
 #
 # The job will cancel as soon as possible and then emit a
 # `JOB_STATUS_CHANGE` event.  Usually, the status will change to
@@ -184,9 +181,9 @@
 
 ##
 # @job-complete:
-#
-# Manually trigger completion of an active job in the READY or STANDBY
-# state.  Completing the job in any other state is an error.
+#     Manually trigger completion of an active job in the READY or
+#     STANDBY state.  Completing the job in any other state is an
+#     error.
 #
 # This is supported only for drive mirroring, where it also switches
 # the device to write to the target path only.  Note that drive
@@ -211,14 +208,13 @@
 
 ##
 # @job-dismiss:
-#
-# Deletes a job that is in the CONCLUDED state.  This command only
-# needs to be run explicitly for jobs that don't have automatic
-# dismiss enabled.  In turn, automatic dismiss may be enabled only for
-# jobs that have @auto-dismiss option, which are `drive-backup`,
-# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit`
-# and `block-stream`.  @auto-dismiss is enabled by default for these
-# jobs.
+#     Deletes a job that is in the CONCLUDED state.  This command only
+#     needs to be run explicitly for jobs that don't have automatic
+#     dismiss enabled.  In turn, automatic dismiss may be enabled only
+#     for jobs that have @auto-dismiss option, which are
+#     `drive-backup`, `blockdev-backup`, `drive-mirror`,
+#     `blockdev-mirror`, `block-commit` and `block-stream`.
+#     @auto-dismiss is enabled by default for these jobs.
 #
 # This command will refuse to operate on any job that has not yet
 # reached its terminal state, CONCLUDED.  For jobs that make use of
@@ -233,11 +229,10 @@
 
 ##
 # @job-finalize:
-#
-# Instructs all jobs in a transaction (or a single job if it is not
-# part of any transaction) to finalize any graph changes and do any
-# necessary cleanup.  This command requires that all involved jobs are
-# in the PENDING state.
+#     Instructs all jobs in a transaction (or a single job if it is
+#     not part of any transaction) to finalize any graph changes and
+#     do any necessary cleanup.  This command requires that all
+#     involved jobs are in the PENDING state.
 #
 # For jobs in a transaction, instructing one job to finalize will
 # force ALL jobs in the transaction to finalize, so it is only
diff --git a/qapi/machine.json b/qapi/machine.json
index aaecd151407..45e79c18b09 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1978,12 +1978,12 @@
 ##
 # @query-cpu-model-comparison:
 #
-# Compares two CPU models, @modela and @modelb, returning how they
-# compare in a specific configuration.  The results indicates how both
-# models compare regarding runnability.  This result can be used by
-# tooling to make decisions if a certain CPU model will run in a
-# certain configuration or if a compatible CPU model has to be created
-# by baselining.
+#     Compares two CPU models, @modela and @modelb, returning how they
+#     compare in a specific configuration.  The results indicates how
+#     both models compare regarding runnability.  This result can be
+#     used by tooling to make decisions if a certain CPU model will
+#     run in a certain configuration or if a compatible CPU model has
+#     to be created by baselining.
 #
 # Usually, a CPU model is compared against the maximum possible CPU
 # model of a certain configuration (e.g. the "host" model for KVM).
@@ -2034,10 +2034,10 @@
 ##
 # @query-cpu-model-baseline:
 #
-# Baseline two CPU models, @modela and @modelb, creating a compatible
-# third model.  The created model will always be a static,
-# migration-safe CPU model (see "static" CPU model expansion for
-# details).
+#     Baseline two CPU models, @modela and @modelb, creating a
+#     compatible third model.  The created model will always be a
+#     static, migration-safe CPU model (see "static" CPU model
+#     expansion for details).
 #
 # This interface can be used by tooling to create a compatible CPU
 # model out two CPU models.  The created CPU model will be identical
@@ -2105,11 +2105,11 @@
 
 ##
 # @query-cpu-model-expansion:
-#
-# Expands a given CPU model, @model, (or a combination of CPU model +
-# additional options) to different granularities, specified by @type,
-# allowing tooling to get an understanding what a specific CPU model
-# looks like in QEMU under a certain configuration.
+#     Expands a given CPU model, @model, (or a combination of CPU
+#     model + additional options) to different granularities,
+#     specified by @type, allowing tooling to get an understanding
+#     what a specific CPU model looks like in QEMU under a certain
+#     configuration.
 #
 # This interface can be used to query the "host" CPU model.
 #
diff --git a/qapi/migration.json b/qapi/migration.json
index 13c446b922f..2c490736019 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -1820,9 +1820,9 @@
 
 ##
 # @calc-dirty-rate:
-#
-# Start measuring dirty page rate of the VM.  Results can be retrieved
-# with `query-dirty-rate` after measurements are completed.
+#     Start measuring dirty page rate of the VM.  Results can be
+#     retrieved with `query-dirty-rate` after measurements are
+#     completed.
 #
 # Dirty page rate is the number of pages changed in a given time
 # period expressed in MiB/s.  The following methods of calculation are
@@ -1939,8 +1939,7 @@
 
 ##
 # @set-vcpu-dirty-limit:
-#
-# Set the upper limit of dirty page rate for virtual CPUs.
+#     Set the upper limit of dirty page rate for virtual CPUs.
 #
 # Requires KVM with accelerator property "dirty-ring-size" set.  A
 # virtual CPU's dirty page rate is a measure of its memory load.  To
diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json
index 78ec9aec647..6e0ab46b8ea 100644
--- a/qapi/misc-i386.json
+++ b/qapi/misc-i386.json
@@ -5,10 +5,9 @@
 
 ##
 # @rtc-reset-reinjection:
-#
-# Reset the RTC interrupt reinjection backlog.  Can be used if another
-# mechanism to synchronize guest time is in effect, for example QEMU
-# guest agent's `guest-set-time` command.
+#     Reset the RTC interrupt reinjection backlog.  Can be used if
+#     another mechanism to synchronize guest time is in effect, for
+#     example QEMU guest agent's `guest-set-time` command.
 #
 # Use of this command is only applicable for x86 machines with an RTC,
 # and on other machines will silently return without performing any
@@ -119,8 +118,7 @@
 
 ##
 # @query-sev:
-#
-# Return information about SEV/SEV-ES/SEV-SNP.
+#     Return information about SEV/SEV-ES/SEV-SNP.
 #
 # If unavailable due to an incompatible configuration the returned
 # @enabled field is set to 'false' and the state of all other fields
@@ -149,8 +147,7 @@
 
 ##
 # @query-sev-launch-measure:
-#
-# Query the SEV/SEV-ES guest launch information.
+#     Query the SEV/SEV-ES guest launch information.
 #
 # This is only valid on x86 machines configured with KVM and the
 # 'sev-guest' confidential virtualization object.  The launch
@@ -199,8 +196,7 @@
 
 ##
 # @query-sev-capabilities:
-#
-# Get SEV capabilities.
+#     Get SEV capabilities.
 #
 # This is only supported on AMD X86 platforms with KVM enabled.
 #
@@ -220,8 +216,7 @@
 
 ##
 # @sev-inject-launch-secret:
-#
-# Inject a secret blob into a SEV/SEV-ES guest's memory.
+#     Inject a secret blob into a SEV/SEV-ES guest's memory.
 #
 # This is only valid on x86 machines configured with KVM and the
 # 'sev-guest' confidential virtualization object.  SEV-SNP guests do
@@ -257,8 +252,7 @@
 
 ##
 # @query-sev-attestation-report:
-#
-# Get the SEV attestation report.
+#     Get the SEV attestation report.
 #
 # This is only valid on x86 machines configured with KVM and the
 # 'sev-guest' confidential virtualization object.  The attestation
diff --git a/qapi/misc.json b/qapi/misc.json
index 374711ac6c7..44f38b60448 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -12,9 +12,8 @@
 
 ##
 # @add_client:
-#
-# Allow client connections for VNC, Spice and socket based character
-# devices to be passed in to QEMU via SCM_RIGHTS.
+#     Allow client connections for VNC, Spice and socket based
+#     character devices to be passed in to QEMU via SCM_RIGHTS.
 #
 # If the FD associated with @fdname is not a socket, the command will
 # fail and the FD will be closed.
diff --git a/qapi/net.json b/qapi/net.json
index 50dc3137182..6beabc0e9dd 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -37,8 +37,7 @@
 
 ##
 # @netdev_add:
-#
-# Add a network backend.
+#     Add a network backend.
 #
 # Additional arguments depend on the type.
 #
diff --git a/qapi/stats.json b/qapi/stats.json
index af57ec08546..e9d05390c31 100644
--- a/qapi/stats.json
+++ b/qapi/stats.json
@@ -175,9 +175,8 @@
 
 ##
 # @query-stats:
-#
-# Return runtime-collected statistics for objects such as the VM or
-# its vCPUs.
+#     Return runtime-collected statistics for objects such as the VM
+#     or its vCPUs.
 #
 # The arguments are a `StatsFilter` and specify the provider and
 # objects to return statistics about.
diff --git a/qapi/transaction.json b/qapi/transaction.json
index c0dc811ba61..02e1d072c63 100644
--- a/qapi/transaction.json
+++ b/qapi/transaction.json
@@ -198,9 +198,9 @@
 ##
 # @transaction:
 #
-# Executes a number of transactionable QMP commands atomically.  If
-# any operation fails, then the entire set of actions will be
-# abandoned and the appropriate error returned.
+#     Executes a number of transactionable QMP commands atomically.
+#     If any operation fails, then the entire set of actions will be
+#     abandoned and the appropriate error returned.
 #
 # For external snapshots, the dictionary contains the device, the file
 # to use for the new snapshot, and the format.  The default format, if
diff --git a/qapi/ui.json b/qapi/ui.json
index a59cd635774..73ee2cb2056 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -1198,8 +1198,7 @@
 
 ##
 # @input-send-event:
-#
-# Send input event(s) to guest.
+#     Send input event(s) to guest.
 #
 # The @device and @head parameters can be used to send the input event
 # to specific input devices in case (a) multiple input devices of the
-- 
2.55.0

Re: [PATCH 5/9] qapi: split intro sections for commands

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> For commands, the primary difference between "intro" and "details" is
> that the intro will appear "above the fold" on generated HTML
> documentation (i.e. before argument/features tables), and "details"
> will appear afterwards.

Yes, but this isn't what this patch's split is about just yet, isn't it?

Consider block-resize.  Before the patch:

    ##
    # @block_resize:
    #
    # Resize a block image while a guest is running.
    #
    # Either @device or @node-name must be set but not both.
    #
    # @device: the name of the device to get the image resized
    #
    # @node-name: graph node name to get the image resized (Since 2.0)
    #
    # @size: new image size in bytes
    #
    # Errors:
    #     - If @device is not a valid block device, DeviceNotFound
    #
    # Since: 0.14
    #
    # .. qmp-example::
    #
    #     -> { "execute": "block_resize",
    #          "arguments": { "device": "scratch", "size": 1073741824 } }
    #     <- { "return": {} }
    ##

Rendered like

    Command block_resize (Since: 0.14)

       Resize a block image while a guest is running.

       Either "device" or "node-name" must be set but not both.

       Arguments:
          * **device** ("string", *optional*) -- the name of the device to
            get the image resized

          * **node-name** ("string", *optional*) -- graph node name to get
            the image resized (Since 2.0)

          * **size** ("int") -- new image size in bytes

       Errors:
          * If "device" is not a valid block device, DeviceNotFound

       Example::

          -> { "execute": "block_resize",
               "arguments": { "device": "scratch", "size": 1073741824 } }
          <- { "return": {} }

The patch splits its first section, namely

    # Resize a block image while a guest is running.
    #
    # Either @device or @node-name must be set but not both.

The first sentence becomes "intro".  The second remains "plain" (for
now).  Rendered documentation doesn't change.

"For now" because I understand you plan to eliminate "plain" sections by
moving them down.

Fair?

> Review notes: As these are commands, the split is more
> arbitrary. These commands all have quite a bit of text, so I tended to
> split off just the first sentence or maybe the first paragraph. Some
> of these are likely candidates for writing a new one-sentence synopsis
> and shuffling most, if not all, of the existing prose down into the
> details.
>
> As an artifact from when these patches were part of a much, much
> larger set of changes, the details split is not physically relocated
> in these patches to keep the diffs simple and obvious to read. This
> can be changed if desired, but it does produce uglier diffs and can
> obscure prose changes where they arise.

I'm fine with leaving "plain" sections in place for now.  To explain
why, I need to take a step back.

Our larger goal is to prepare the ground for the inliner: fixed section
order, "intro" cleaned up.

We want fixed section order to simplify where to inline.  Not just
simpler code, also simpler to predict for documentation writers.

We need "intro" cleaned up so the inliner elides the right stuff and not
the wrong stuff.  While this matters only for types being inlined, we
better clean up all types.  A change in one place may inline a type from
another place.  If that type's "intro" still needs cleanup, there's a
real risk we miss it.

The inliner will work okay even if commands and events don't have clean
"intro".  But we'll want them clean eventually, because it'll improve
the documentation, so why not clean them some now.

Our immediate goal is to convert first sections to "intro" syntax.

We could do a purely mechanical conversion.  This would result in quite
"intro" that make the inliner elide the wrong stuff.  We'd rather avoid
those.

A series that converts everything *and* avoids bad "intro" would be
unreviewable.  We need to do this in multiple steps

I'd like to minimize the time where we have both old and new syntax.  So
I collect conversions patches in my tree until the conversion is
complete, or at least complete enough to merge into master.

To make this plan work, we need to finish the job fairly quickly.  That
means we need to keep the job sufficiently simple.  We're aiming for a
mostly mechanical conversion that gets the "intro" contents mostly
right, and is easy to review.  Involves splitting some first sections
into "intro" and "plain".  The latter will need further cleanup later.

Makes sense?

Assuming it does: we don't have to get the split between "intro" and
"plain" exactly right now.  It doesn't affect rendered documentation
until later, and we'll revisit "plain" anyway.  So I'll refrain from
discussing what contents belongs on which side of these splits.

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/block-core.json   | 76 ++++++++++++++++++------------------------
>  qapi/block-export.json |  3 +-
>  qapi/block.json        | 42 +++++++++++------------
>  qapi/control.json      |  3 +-
>  qapi/introspect.json   | 16 ++++-----
>  qapi/job.json          | 43 +++++++++++-------------
>  qapi/machine.json      | 30 ++++++++---------
>  qapi/migration.json    |  9 +++--
>  qapi/misc-i386.json    | 22 +++++-------
>  qapi/misc.json         |  5 ++-
>  qapi/net.json          |  3 +-
>  qapi/stats.json        |  5 ++-
>  qapi/transaction.json  |  6 ++--
>  qapi/ui.json           |  3 +-
>  14 files changed, 118 insertions(+), 148 deletions(-)
>
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index c505369aeb2..ec052f6bd2d 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -1516,8 +1516,7 @@
>  
>  ##
>  # @block_resize:
> -#
> -# Resize a block image while a guest is running.
> +#     Resize a block image while a guest is running.
>  #
>  # Either @device or @node-name must be set but not both.
>  #
> @@ -1842,9 +1841,8 @@
>  
>  ##
>  # @block-commit:
> -#
> -# Live commit of data from overlay image nodes into backing nodes -
> -# i.e., writes data between 'top' and 'base' into 'base'.
> +#     Live commit of data from overlay image nodes into backing nodes
> +#     - i.e., writes data between 'top' and 'base' into 'base'.
>  #
>  # If top == base, that is an error.  If top has no overlays on top of
>  # it, or if it is in use by a writer, the job will not be completed by
> @@ -2824,8 +2822,7 @@
>  
>  ##
>  # @block-stream:
> -#
> -# Copy data from a backing file into a block device.
> +#     Copy data from a backing file into a block device.
>  #
>  # The block streaming operation is performed in the background until
>  # the entire backing file has been copied.  This command returns
> @@ -2936,8 +2933,7 @@
>  
>  ##
>  # @block-job-set-speed:
> -#
> -# Set maximum speed for a background block operation.
> +#     Set maximum speed for a background block operation.
>  #
>  # This command can only be issued when there is an active block job.
>  #
> @@ -2962,8 +2958,7 @@
>  
>  ##
>  # @block-job-cancel:
> -#
> -# Stop an active background block operation.
> +#     Stop an active background block operation.
>  #
>  # This command returns immediately after marking the active background
>  # block operation for cancellation.  It is an error to call this
> @@ -3005,8 +3000,7 @@
>  
>  ##
>  # @block-job-pause:
> -#
> -# Pause an active background block operation.
> +#     Pause an active background block operation.
>  #
>  # This command returns immediately after marking the active job for
>  # pausing.  Pausing an already paused job is an error.
> @@ -3038,8 +3032,7 @@
>  
>  ##
>  # @block-job-resume:
> -#
> -# Resume an active background block operation.
> +#     Resume an active background block operation.
>  #
>  # This command returns immediately after resuming a paused job.
>  # Resuming an already running job is an error.
> @@ -3067,9 +3060,9 @@
>  
>  ##
>  # @block-job-complete:
> -#
> -# Manually trigger completion of an active job in the READY or STANDBY
> -# state.  Completing the job in any other state is an error.
> +#     Manually trigger completion of an active job in the READY or
> +#     STANDBY state.  Completing the job in any other state is an
> +#     error.
>  #
>  # This is supported only for drive mirroring, where it also switches
>  # the device to write to the target path only.  Note that drive
> @@ -3107,14 +3100,13 @@
>  
>  ##
>  # @block-job-dismiss:
> -#
> -# Deletes a job that is in the CONCLUDED state.  This command only
> -# needs to be run explicitly for jobs that don't have automatic
> -# dismiss enabled.  In turn, automatic dismiss may be enabled only for
> -# jobs that have @auto-dismiss option, which are `drive-backup`,
> -# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit`
> -# and `block-stream`.  @auto-dismiss is enabled by default for these
> -# jobs.
> +#     Deletes a job that is in the CONCLUDED state.  This command only
> +#     needs to be run explicitly for jobs that don't have automatic
> +#     dismiss enabled.  In turn, automatic dismiss may be enabled only
> +#     for jobs that have @auto-dismiss option, which are
> +#     `drive-backup`, `blockdev-backup`, `drive-mirror`,
> +#     `blockdev-mirror`, `block-commit` and `block-stream`.
> +#     @auto-dismiss is enabled by default for these jobs.
>  #
>  # This command will refuse to operate on any job that has not yet
>  # reached its terminal state, CONCLUDED.  For jobs that make use of
> @@ -3136,11 +3128,10 @@
>  
>  ##
>  # @block-job-finalize:
> -#
> -# Instructs all jobs in a transaction (or a single job if it is not
> -# part of any transaction) to finalize any graph changes and do any
> -# necessary cleanup.  This command requires that all involved jobs are
> -# in the PENDING state.
> +#     Instructs all jobs in a transaction (or a single job if it is
> +#     not part of any transaction) to finalize any graph changes and
> +#     do any necessary cleanup.  This command requires that all
> +#     involved jobs are in the PENDING state.
>  #
>  # For jobs in a transaction, instructing one job to finalize will
>  # force ALL jobs in the transaction to finalize, so it is only
> @@ -4882,14 +4873,13 @@
>  
>  ##
>  # @blockdev-reopen:
> -#
> -# Reopens one or more block devices using the given set of options.
> -# Any option not specified will be reset to its default value
> -# regardless of its previous status.  If an option cannot be changed
> -# or a particular driver does not support reopening then the command
> -# will return an error.  All devices in the list are reopened in one
> -# transaction, so if one of them fails then the whole transaction is
> -# cancelled.
> +#     Reopens one or more block devices using the given set of
> +#     options.  Any option not specified will be reset to its default
> +#     value regardless of its previous status.  If an option cannot be
> +#     changed or a particular driver does not support reopening then
> +#     the command will return an error.  All devices in the list are
> +#     reopened in one transaction, so if one of them fails then the
> +#     whole transaction is cancelled.
>  #
>  # The command receives a list of block devices to reopen.  For each
>  # one of them, the top-level @node-name option (from
> @@ -4961,9 +4951,8 @@
>  
>  ##
>  # @blockdev-set-active:
> -#
> -# Activate or deactivate a block device.  Use this to manage the
> -# handover of block devices on migration with qemu-storage-daemon.
> +#     Activate or deactivate a block device.  Use this to manage the
> +#     handover of block devices on migration with qemu-storage-daemon.
>  #
>  # Activating a node automatically activates all of its child nodes
>  # first.  Deactivating a node automatically deactivates any of its
> @@ -5876,8 +5865,7 @@
>  
>  ##
>  # @x-blockdev-change:
> -#
> -# Dynamically reconfigure the block driver state graph.
> +#     Dynamically reconfigure the block driver state graph.
>  #
>  # Currently only supports adding and deleting quorum children.  A
>  # child will be added at the end of the list of children.  Its
> diff --git a/qapi/block-export.json b/qapi/block-export.json
> index e9f7e72c8ee..77459f6321b 100644
> --- a/qapi/block-export.json
> +++ b/qapi/block-export.json
> @@ -235,8 +235,7 @@
>  
>  ##
>  # @nbd-server-add:
> -#
> -# Export a block node to QEMU's embedded NBD server.
> +#     Export a block node to QEMU's embedded NBD server.
>  #
>  # The export name will be used as the id for the resulting block
>  # export.
> diff --git a/qapi/block.json b/qapi/block.json
> index 15f08372564..73aad7f4f2b 100644
> --- a/qapi/block.json
> +++ b/qapi/block.json
> @@ -128,11 +128,25 @@
>  
>  ##
>  # @blockdev-open-tray:
> +#     Opens a block device's tray.
>  #
> -# Opens a block device's tray.  If there is a block driver state tree
> -# inserted as a medium, it will become inaccessible to the guest (but
> -# it will remain associated to the block device, so closing the tray
> -# will make it accessible again).
> +# @device: Block device name
> +#
> +# @id: The name or QOM path of the guest device (since: 2.8)
> +#
> +# @force: if false (the default), an eject request will be sent to the
> +#     guest if it has locked the tray (and the tray will not be opened
> +#     immediately); if true, the tray will be opened regardless of
> +#     whether it is locked
> +#
> +# Features:
> +#
> +# @deprecated: Member @device is deprecated.  Use @id instead.
> +#
> +# If there is a block driver state tree inserted as a medium, it will
> +# become inaccessible to the guest (but it will remain associated to
> +# the block device, so closing the tray will make it accessible
> +# again).
>  #
>  # If the tray was already open before, this will be a no-op.
>  #
> @@ -145,19 +159,6 @@
>  #   device attached to it
>  # - if the guest device does not have an actual tray
>  #
> -# @device: Block device name
> -#
> -# @id: The name or QOM path of the guest device (since: 2.8)
> -#
> -# @force: if false (the default), an eject request will be sent to the
> -#     guest if it has locked the tray (and the tray will not be opened
> -#     immediately); if true, the tray will be opened regardless of
> -#     whether it is locked
> -#
> -# Features:
> -#
> -# @deprecated: Member @device is deprecated.  Use @id instead.
> -#
>  # Since: 2.5
>  #
>  # .. qmp-example::

Here you don't just split, you also move the second part of the split
down.  Let's leave that for later, as discussed in review of your commit
message.

> @@ -429,8 +430,10 @@
>  
>  ##
>  # @block_set_io_throttle:
> +#     Change I/O throttle limits for a block drive.
>  #
> -# Change I/O throttle limits for a block drive.
> +# Errors:
> +#     - If @device is not a valid block device, DeviceNotFound
>  #
>  # Since QEMU 2.4, each device with I/O limits is member of a throttle
>  # group.
> @@ -453,9 +456,6 @@
>  # case the device will be removed from its group and the rest of its
>  # members will not be affected.  The 'group' parameter is ignored.
>  #
> -# Errors:
> -#     - If @device is not a valid block device, DeviceNotFound
> -#
>  # Since: 1.1
>  #
>  # .. qmp-example::

Likewise.

> diff --git a/qapi/control.json b/qapi/control.json
> index 0fc465936d8..b19ca910d5f 100644
> --- a/qapi/control.json
> +++ b/qapi/control.json
> @@ -152,8 +152,7 @@
>  
>  ##
>  # @quit:
> -#
> -# Request graceful QEMU process termination.
> +#     Request graceful QEMU process termination.
>  #
>  # While every attempt is made to send the QMP response before
>  # terminating, this is not guaranteed.  When using this interface, a
> diff --git a/qapi/introspect.json b/qapi/introspect.json
> index bd42aac3358..d579e5c8554 100644
> --- a/qapi/introspect.json
> +++ b/qapi/introspect.json
> @@ -17,15 +17,15 @@
>  
>  ##
>  # @query-qmp-schema:
> +#     Command `query-qmp-schema` exposes the QMP wire ABI as an array
> +#     of `SchemaInfo`.  This lets QMP clients figure out what commands
> +#     and events are available in this QEMU, and their parameters and
> +#     results.
>  #
> -# Command `query-qmp-schema` exposes the QMP wire ABI as an array of
> -# `SchemaInfo`.  This lets QMP clients figure out what commands and
> -# events are available in this QEMU, and their parameters and results.
> -#
> -# However, the `SchemaInfo` can't reflect all the rules and
> -# restrictions that apply to QMP.  It's interface introspection
> -# (figuring out what's there), not interface specification.  The
> -# specification is in the QAPI schema.
> +# The `SchemaInfo` can't reflect all the rules and restrictions that

You delete "However, ".  Leave for later, when we revisit the "plain"
sections.


> +# apply to QMP.  It's interface introspection (figuring out what's
> +# there), not interface specification.  The specification is in the
> +# QAPI schema.
>  #
>  # Furthermore, while we strive to keep the QMP wire format
>  # backwards-compatible across QEMU versions, the introspection output
> diff --git a/qapi/job.json b/qapi/job.json
> index b68d7292423..1aec4ceb9f1 100644
> --- a/qapi/job.json
> +++ b/qapi/job.json
> @@ -128,8 +128,7 @@
>  
>  ##
>  # @job-pause:
> -#
> -# Pause an active job.
> +#     Pause an active job.
>  #
>  # This command returns immediately after marking the active job for
>  # pausing.  Pausing an already paused job is an error.
> @@ -148,8 +147,7 @@
>  
>  ##
>  # @job-resume:
> -#
> -# Resume a paused job.
> +#     Resume a paused job.
>  #
>  # This command returns immediately after resuming a paused job.
>  # Resuming an already running job is an error.
> @@ -165,10 +163,9 @@
>  
>  ##
>  # @job-cancel:
> -#
> -# Instruct an active background job to cancel at the next opportunity.
> -# This command returns immediately after marking the active job for
> -# cancellation.
> +#     Instruct an active background job to cancel at the next
> +#     opportunity.  This command returns immediately after marking the
> +#     active job for cancellation.
>  #
>  # The job will cancel as soon as possible and then emit a
>  # `JOB_STATUS_CHANGE` event.  Usually, the status will change to
> @@ -184,9 +181,9 @@
>  
>  ##
>  # @job-complete:
> -#
> -# Manually trigger completion of an active job in the READY or STANDBY
> -# state.  Completing the job in any other state is an error.
> +#     Manually trigger completion of an active job in the READY or
> +#     STANDBY state.  Completing the job in any other state is an
> +#     error.
>  #
>  # This is supported only for drive mirroring, where it also switches
>  # the device to write to the target path only.  Note that drive
> @@ -211,14 +208,13 @@
>  
>  ##
>  # @job-dismiss:
> -#
> -# Deletes a job that is in the CONCLUDED state.  This command only
> -# needs to be run explicitly for jobs that don't have automatic
> -# dismiss enabled.  In turn, automatic dismiss may be enabled only for
> -# jobs that have @auto-dismiss option, which are `drive-backup`,
> -# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit`
> -# and `block-stream`.  @auto-dismiss is enabled by default for these
> -# jobs.
> +#     Deletes a job that is in the CONCLUDED state.  This command only
> +#     needs to be run explicitly for jobs that don't have automatic
> +#     dismiss enabled.  In turn, automatic dismiss may be enabled only
> +#     for jobs that have @auto-dismiss option, which are
> +#     `drive-backup`, `blockdev-backup`, `drive-mirror`,
> +#     `blockdev-mirror`, `block-commit` and `block-stream`.
> +#     @auto-dismiss is enabled by default for these jobs.
>  #
>  # This command will refuse to operate on any job that has not yet
>  # reached its terminal state, CONCLUDED.  For jobs that make use of
> @@ -233,11 +229,10 @@
>  
>  ##
>  # @job-finalize:
> -#
> -# Instructs all jobs in a transaction (or a single job if it is not
> -# part of any transaction) to finalize any graph changes and do any
> -# necessary cleanup.  This command requires that all involved jobs are
> -# in the PENDING state.
> +#     Instructs all jobs in a transaction (or a single job if it is
> +#     not part of any transaction) to finalize any graph changes and
> +#     do any necessary cleanup.  This command requires that all
> +#     involved jobs are in the PENDING state.
>  #
>  # For jobs in a transaction, instructing one job to finalize will
>  # force ALL jobs in the transaction to finalize, so it is only
> diff --git a/qapi/machine.json b/qapi/machine.json
> index aaecd151407..45e79c18b09 100644
> --- a/qapi/machine.json
> +++ b/qapi/machine.json
> @@ -1978,12 +1978,12 @@
>  ##
>  # @query-cpu-model-comparison:
>  #

Drop the blank line.

> -# Compares two CPU models, @modela and @modelb, returning how they
> -# compare in a specific configuration.  The results indicates how both
> -# models compare regarding runnability.  This result can be used by
> -# tooling to make decisions if a certain CPU model will run in a
> -# certain configuration or if a compatible CPU model has to be created
> -# by baselining.
> +#     Compares two CPU models, @modela and @modelb, returning how they
> +#     compare in a specific configuration.  The results indicates how
> +#     both models compare regarding runnability.  This result can be
> +#     used by tooling to make decisions if a certain CPU model will
> +#     run in a certain configuration or if a compatible CPU model has
> +#     to be created by baselining.
>  #
>  # Usually, a CPU model is compared against the maximum possible CPU
>  # model of a certain configuration (e.g. the "host" model for KVM).
> @@ -2034,10 +2034,10 @@
>  ##
>  # @query-cpu-model-baseline:
>  #

Drop the blank line.

> -# Baseline two CPU models, @modela and @modelb, creating a compatible
> -# third model.  The created model will always be a static,
> -# migration-safe CPU model (see "static" CPU model expansion for
> -# details).
> +#     Baseline two CPU models, @modela and @modelb, creating a
> +#     compatible third model.  The created model will always be a
> +#     static, migration-safe CPU model (see "static" CPU model
> +#     expansion for details).
>  #
>  # This interface can be used by tooling to create a compatible CPU
>  # model out two CPU models.  The created CPU model will be identical
> @@ -2105,11 +2105,11 @@
>  
>  ##
>  # @query-cpu-model-expansion:
> -#
> -# Expands a given CPU model, @model, (or a combination of CPU model +
> -# additional options) to different granularities, specified by @type,
> -# allowing tooling to get an understanding what a specific CPU model
> -# looks like in QEMU under a certain configuration.
> +#     Expands a given CPU model, @model, (or a combination of CPU
> +#     model + additional options) to different granularities,
> +#     specified by @type, allowing tooling to get an understanding
> +#     what a specific CPU model looks like in QEMU under a certain
> +#     configuration.
>  #
>  # This interface can be used to query the "host" CPU model.
>  #
> diff --git a/qapi/migration.json b/qapi/migration.json
> index 13c446b922f..2c490736019 100644
> --- a/qapi/migration.json
> +++ b/qapi/migration.json
> @@ -1820,9 +1820,9 @@
>  
>  ##
>  # @calc-dirty-rate:
> -#
> -# Start measuring dirty page rate of the VM.  Results can be retrieved
> -# with `query-dirty-rate` after measurements are completed.
> +#     Start measuring dirty page rate of the VM.  Results can be
> +#     retrieved with `query-dirty-rate` after measurements are
> +#     completed.
>  #
>  # Dirty page rate is the number of pages changed in a given time
>  # period expressed in MiB/s.  The following methods of calculation are
> @@ -1939,8 +1939,7 @@
>  
>  ##
>  # @set-vcpu-dirty-limit:
> -#
> -# Set the upper limit of dirty page rate for virtual CPUs.
> +#     Set the upper limit of dirty page rate for virtual CPUs.
>  #
>  # Requires KVM with accelerator property "dirty-ring-size" set.  A
>  # virtual CPU's dirty page rate is a measure of its memory load.  To
> diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json
> index 78ec9aec647..6e0ab46b8ea 100644
> --- a/qapi/misc-i386.json
> +++ b/qapi/misc-i386.json
> @@ -5,10 +5,9 @@
>  
>  ##
>  # @rtc-reset-reinjection:
> -#
> -# Reset the RTC interrupt reinjection backlog.  Can be used if another
> -# mechanism to synchronize guest time is in effect, for example QEMU
> -# guest agent's `guest-set-time` command.
> +#     Reset the RTC interrupt reinjection backlog.  Can be used if
> +#     another mechanism to synchronize guest time is in effect, for
> +#     example QEMU guest agent's `guest-set-time` command.
>  #
>  # Use of this command is only applicable for x86 machines with an RTC,
>  # and on other machines will silently return without performing any
> @@ -119,8 +118,7 @@
>  
>  ##
>  # @query-sev:
> -#
> -# Return information about SEV/SEV-ES/SEV-SNP.
> +#     Return information about SEV/SEV-ES/SEV-SNP.
>  #
>  # If unavailable due to an incompatible configuration the returned
>  # @enabled field is set to 'false' and the state of all other fields
> @@ -149,8 +147,7 @@
>  
>  ##
>  # @query-sev-launch-measure:
> -#
> -# Query the SEV/SEV-ES guest launch information.
> +#     Query the SEV/SEV-ES guest launch information.
>  #
>  # This is only valid on x86 machines configured with KVM and the
>  # 'sev-guest' confidential virtualization object.  The launch
> @@ -199,8 +196,7 @@
>  
>  ##
>  # @query-sev-capabilities:
> -#
> -# Get SEV capabilities.
> +#     Get SEV capabilities.
>  #
>  # This is only supported on AMD X86 platforms with KVM enabled.
>  #
> @@ -220,8 +216,7 @@
>  
>  ##
>  # @sev-inject-launch-secret:
> -#
> -# Inject a secret blob into a SEV/SEV-ES guest's memory.
> +#     Inject a secret blob into a SEV/SEV-ES guest's memory.
>  #
>  # This is only valid on x86 machines configured with KVM and the
>  # 'sev-guest' confidential virtualization object.  SEV-SNP guests do
> @@ -257,8 +252,7 @@
>  
>  ##
>  # @query-sev-attestation-report:
> -#
> -# Get the SEV attestation report.
> +#     Get the SEV attestation report.
>  #
>  # This is only valid on x86 machines configured with KVM and the
>  # 'sev-guest' confidential virtualization object.  The attestation
> diff --git a/qapi/misc.json b/qapi/misc.json
> index 374711ac6c7..44f38b60448 100644
> --- a/qapi/misc.json
> +++ b/qapi/misc.json
> @@ -12,9 +12,8 @@
>  
>  ##
>  # @add_client:
> -#
> -# Allow client connections for VNC, Spice and socket based character
> -# devices to be passed in to QEMU via SCM_RIGHTS.
> +#     Allow client connections for VNC, Spice and socket based
> +#     character devices to be passed in to QEMU via SCM_RIGHTS.
>  #
>  # If the FD associated with @fdname is not a socket, the command will
>  # fail and the FD will be closed.
> diff --git a/qapi/net.json b/qapi/net.json
> index 50dc3137182..6beabc0e9dd 100644
> --- a/qapi/net.json
> +++ b/qapi/net.json
> @@ -37,8 +37,7 @@
>  
>  ##
>  # @netdev_add:
> -#
> -# Add a network backend.
> +#     Add a network backend.
>  #
>  # Additional arguments depend on the type.
>  #
> diff --git a/qapi/stats.json b/qapi/stats.json
> index af57ec08546..e9d05390c31 100644
> --- a/qapi/stats.json
> +++ b/qapi/stats.json
> @@ -175,9 +175,8 @@
>  
>  ##
>  # @query-stats:
> -#
> -# Return runtime-collected statistics for objects such as the VM or
> -# its vCPUs.
> +#     Return runtime-collected statistics for objects such as the VM
> +#     or its vCPUs.
>  #
>  # The arguments are a `StatsFilter` and specify the provider and
>  # objects to return statistics about.
> diff --git a/qapi/transaction.json b/qapi/transaction.json
> index c0dc811ba61..02e1d072c63 100644
> --- a/qapi/transaction.json
> +++ b/qapi/transaction.json
> @@ -198,9 +198,9 @@
>  ##
>  # @transaction:
>  #

Drop the blank line.

> -# Executes a number of transactionable QMP commands atomically.  If
> -# any operation fails, then the entire set of actions will be
> -# abandoned and the appropriate error returned.
> +#     Executes a number of transactionable QMP commands atomically.
> +#     If any operation fails, then the entire set of actions will be
> +#     abandoned and the appropriate error returned.
>  #
>  # For external snapshots, the dictionary contains the device, the file
>  # to use for the new snapshot, and the format.  The default format, if
> diff --git a/qapi/ui.json b/qapi/ui.json
> index a59cd635774..73ee2cb2056 100644
> --- a/qapi/ui.json
> +++ b/qapi/ui.json
> @@ -1198,8 +1198,7 @@
>  
>  ##
>  # @input-send-event:
> -#
> -# Send input event(s) to guest.
> +#     Send input event(s) to guest.
>  #
>  # The @device and @head parameters can be used to send the input event
>  # to specific input devices in case (a) multiple input devices of the

[PATCH 6/9] qapi: split intro sections for events

[John Snow]

Review notes: Only one event; as in the command splitting patch, the
details section is not physically relocated; I will change this if
requested - but as we are not finished review, I prefer to keep it
this way to ensure mechanical ease of separating "changes" from
"motion" as is customary in our lands.

(Hint: relocating "Since:" and "Details" sections is a colossal amount
of purely mechanical motion, so I recommend we simply deal with it all
at once when we are done agreeing on the splits.)

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

diff --git a/qapi/machine-s390x.json b/qapi/machine-s390x.json
index dcbad9b4039..670a1f9d926 100644
--- a/qapi/machine-s390x.json
+++ b/qapi/machine-s390x.json
@@ -57,8 +57,7 @@
 
 ##
 # @CPU_POLARIZATION_CHANGE:
-#
-# Emitted when the guest asks to change the polarization.
+#     Emitted when the guest asks to change the polarization.
 #
 # The guest can tell the host (via the PTF instruction) whether the
 # CPUs should be provisioned using horizontal or vertical
-- 
2.55.0

Re: [PATCH 6/9] qapi: split intro sections for events

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> Review notes: Only one event; as in the command splitting patch, the
> details section is not physically relocated; I will change this if
> requested - but as we are not finished review, I prefer to keep it
> this way to ensure mechanical ease of separating "changes" from
> "motion" as is customary in our lands.
>
> (Hint: relocating "Since:" and "Details" sections is a colossal amount
> of purely mechanical motion, so I recommend we simply deal with it all
> at once when we are done agreeing on the splits.)

Future patches.  We need to keep the conversion patches focused on just
the conversion, or else they become unreviewable.

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/machine-s390x.json | 3 +--
>  1 file changed, 1 insertion(+), 2 deletions(-)
>
> diff --git a/qapi/machine-s390x.json b/qapi/machine-s390x.json
> index dcbad9b4039..670a1f9d926 100644
> --- a/qapi/machine-s390x.json
> +++ b/qapi/machine-s390x.json
> @@ -57,8 +57,7 @@
>  
>  ##
>  # @CPU_POLARIZATION_CHANGE:
> -#
> -# Emitted when the guest asks to change the polarization.
> +#     Emitted when the guest asks to change the polarization.
>  #
>  # The guest can tell the host (via the PTF instruction) whether the
>  # CPUs should be provisioned using horizontal or vertical

"Intro" conversion is pretty much the same for commands and events.  I'd
squash this into the previous patch, and call it "for commands and
events".  Up to you.

[PATCH 7/9] qapi: split intro sections for enums

[John Snow]

Review notes: Only one enum in this category, and it's fairly trivial.

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

diff --git a/qapi/ui.json b/qapi/ui.json
index 73ee2cb2056..9e3e80a3d70 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -814,10 +814,9 @@
 
 ##
 # @QKeyCode:
+#     An enumeration of key name.
 #
-# An enumeration of key name.
-#
-# This is used by the `send-key` command.
+#     This is used by the `send-key` command.
 #
 # @unmapped: since 2.0
 #
-- 
2.55.0

[PATCH 8/9] qapi: split intro sections for data structs

[John Snow]

The structs of concern in this patch are those for which no other QAPI
definition uses as a data type to describe its own arguments or as a
branch of a union: i.e. they are not currently inlined and as such the
precise semantics of their intro/details split is *currently* of less
concern.

Of course, they could be inlined in the future, so the semantics of
this split are still worth investigating.

Review notes: Similar notes as previous patches in this series with
respect to how splits were determined, and why details were not
physically relocated.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/acpi.json       | 3 +--
 qapi/block-core.json | 5 ++---
 qapi/compat.json     | 3 +--
 qapi/machine.json    | 9 ++++-----
 4 files changed, 8 insertions(+), 12 deletions(-)

diff --git a/qapi/acpi.json b/qapi/acpi.json
index 291a04a7ea4..82e82d7cf89 100644
--- a/qapi/acpi.json
+++ b/qapi/acpi.json
@@ -13,8 +13,7 @@
 
 ##
 # @AcpiTableOptions:
-#
-# Specify an ACPI table on the command line to load.
+#     Specify an ACPI table on the command line to load.
 #
 # At most one of @file and @data can be specified.  The list of files
 # specified by any one of them is loaded and concatenated in order.
diff --git a/qapi/block-core.json b/qapi/block-core.json
index ec052f6bd2d..80f6c41c381 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -803,9 +803,8 @@
 
 ##
 # @BlockMeasureInfo:
-#
-# Image file size calculation information.  This structure describes
-# the size requirements for creating a new image file.
+#     Image file size calculation information.  This structure
+#     describes the size requirements for creating a new image file.
 #
 # The size requirements depend on the new image file format.  File
 # size always equals virtual disk size for the 'raw' format, even for
diff --git a/qapi/compat.json b/qapi/compat.json
index ef1853b9acd..b42d142ddcc 100644
--- a/qapi/compat.json
+++ b/qapi/compat.json
@@ -37,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.
 #
diff --git a/qapi/machine.json b/qapi/machine.json
index 45e79c18b09..05a2851c0fc 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1606,9 +1606,9 @@
 
 ##
 # @SMPConfiguration:
-#
-# Schema for CPU topology configuration.  A missing value lets QEMU
-# figure out a suitable value based on the ones that are provided.
+#     Schema for CPU topology configuration.  A missing value lets
+#     QEMU figure out a suitable value based on the ones that are
+#     provided.
 #
 # The members other than @cpus and @maxcpus define a topology of
 # containers.
@@ -1867,8 +1867,7 @@
 
 ##
 # @CpuModelInfo:
-#
-# Virtual CPU model.
+#     Virtual CPU model.
 #
 # A CPU model consists of the name of a CPU definition, to which delta
 # changes are applied (e.g. features added/removed).  Most magic
-- 
2.55.0

[PATCH 9/9] qapi: split intro sections for inlinable structs

[John Snow]

This patch splits the intro/details section for structs which are used
in an inlinable context; i.e. structs used either as arguments for a
command/event, or used as a branch of a union. The QAPI documentation
block for these entities will have their "intro" section removed when
inlined into other contexts, but may still display the intro section
on generated documentation *IF* these structs are also used as an
argument or return type.

Review notes: Same ol' Same ol'.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/block-export.json | 5 ++---
 qapi/crypto.json       | 3 +--
 qapi/machine.json      | 3 +--
 qapi/qom.json          | 9 +++------
 4 files changed, 7 insertions(+), 13 deletions(-)

diff --git a/qapi/block-export.json b/qapi/block-export.json
index 77459f6321b..e3cee2fb5ce 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -154,9 +154,8 @@
 
 ##
 # @BlockExportOptionsFuse:
-#
-# Options for exporting a block graph node on some (file) mountpoint
-# as a raw image.
+#     Options for exporting a block graph node on some (file)
+#     mountpoint as a raw image.
 #
 # Multi-threading note: The FUSE export supports multi-threading.
 # Currently, requests are distributed across these threads in a
diff --git a/qapi/crypto.json b/qapi/crypto.json
index f85d1cebed3..5ae07d650a6 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -429,8 +429,7 @@
 
 ##
 # @SecretProperties:
-#
-# Properties for secret objects.
+#     Properties for secret objects.
 #
 # Either @data or @file must be provided, but not both.
 #
diff --git a/qapi/machine.json b/qapi/machine.json
index 05a2851c0fc..b1064b53ae3 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -899,8 +899,7 @@
 
 ##
 # @CpuInstanceProperties:
-#
-# Properties identifying a CPU.
+#     Properties identifying a CPU.
 #
 # Which members are optional and which mandatory depends on the
 # architecture and board.
diff --git a/qapi/qom.json b/qapi/qom.json
index 3de06488768..d80dd5976ed 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -456,8 +456,7 @@
 
 ##
 # @FilterRedirectorProperties:
-#
-# Properties for filter-redirector objects.
+#     Properties for filter-redirector objects.
 #
 # At least one of @indev or @outdev must be present.  If both are
 # present, they must not refer to the same character device backend.
@@ -756,8 +755,7 @@
 
 ##
 # @MemoryBackendShmProperties:
-#
-# Properties for memory-backend-shm objects.
+#     Properties for memory-backend-shm objects.
 #
 # This memory backend supports only shared memory, which is the
 # default.
@@ -771,8 +769,7 @@
 
 ##
 # @MemoryBackendEpcProperties:
-#
-# Properties for memory-backend-epc objects.
+#     Properties for memory-backend-epc objects.
 #
 # The @merge boolean option is false by default with epc
 #
-- 
2.55.0