[PATCH v2 00/10] qapi: convert/split remaining QAPI/QMP intro sections

[PATCH v2 00/10] qapi: convert/split remaining QAPI/QMP intro sections

[John Snow]

Depending on what order you read these in, this series is either the
second-to-last batch or the very last batch.

This series covers the trickiest bits of qapi/qapi-schema.json, ones
that involve multiple paragraphs and decisions over where exactly to
place the split. Currently there are only some very minor prose
rewrites the break apart intro statements from paragraphs where deemed
appropriate.

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 (10):
  qapi: split intro for HV_BALLOON_STATUS_REPORT
  qapi: convert/split intros for block-core.json commands
  qapi: convert/split intros for block commands
  qapi: convert/split intros for job.json commands
  qapi: convert/split intros for misc-i386.json commands
  qapi: convert/split intros for commands
  qapi: convert/split intros for enums
  qapi: split intro sections for events
  qapi: split intro sections for data structs
  qapi: split intro sections for inlinable structs

 qapi/acpi.json          |   3 +-
 qapi/block-core.json    | 131 +++++++++++++++++-----------------------
 qapi/block-export.json  |   8 +--
 qapi/block.json         |  33 +++++-----
 qapi/compat.json        |   3 +-
 qapi/control.json       |   3 +-
 qapi/crypto.json        |   3 +-
 qapi/introspect.json    |  16 ++---
 qapi/job.json           |  42 ++++++-------
 qapi/machine-s390x.json |   3 +-
 qapi/machine.json       |  78 +++++++++++-------------
 qapi/migration.json     |  12 ++--
 qapi/misc-arm.json      |   5 +-
 qapi/misc-i386.json     |  22 +++----
 qapi/misc.json          |   8 +--
 qapi/net.json           |  37 +++++-------
 qapi/qdev.json          |   9 ++-
 qapi/qom.json           |   9 +--
 qapi/stats.json         |   5 +-
 qapi/transaction.json   |   6 +-
 qapi/ui.json            |   8 +--
 21 files changed, 192 insertions(+), 252 deletions(-)

-- 
2.55.0

[PATCH v2 02/10] qapi: convert/split intros for block-core.json commands

[John Snow]

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

diff --git a/qapi/block-core.json b/qapi/block-core.json
index 802a4af74ed..13981d7e69d 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1556,8 +1556,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.
 #
@@ -1812,13 +1811,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:
 #
@@ -1883,9 +1881,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
@@ -2510,16 +2507,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
@@ -2865,8 +2861,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
@@ -2977,8 +2972,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.
 #
@@ -3003,8 +2997,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
@@ -3046,8 +3039,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.
@@ -3079,8 +3071,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.
@@ -3108,9 +3099,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
@@ -3148,14 +3139,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
@@ -3177,11 +3167,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
@@ -4917,14 +4906,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
@@ -4996,9 +4984,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
@@ -5881,15 +5868,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.
 #
@@ -5911,8 +5897,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
@@ -5971,11 +5956,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
 #
-- 
2.55.0

[PATCH v2 04/10] qapi: convert/split intros for job.json commands

[John Snow]

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

diff --git a/qapi/job.json b/qapi/job.json
index b68d7292423..aa75a8efa24 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,14 @@
 
 ##
 # @job-dismiss:
+#     Deletes a job that is in the CONCLUDED state.
 #
-# 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 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 +230,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
-- 
2.55.0

[PATCH v2 06/10] qapi: convert/split intros for commands

[John Snow]

This patch converts or splits intro sections for commands with more
than one paragraph of text.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/control.json     |  3 +--
 qapi/introspect.json  | 16 ++++++++--------
 qapi/machine.json     | 31 +++++++++++++++----------------
 qapi/migration.json   | 12 +++++-------
 qapi/misc-arm.json    |  5 ++---
 qapi/misc.json        |  8 +++-----
 qapi/net.json         |  3 +--
 qapi/qdev.json        |  9 ++++-----
 qapi/stats.json       |  5 ++---
 qapi/transaction.json |  6 +++---
 qapi/ui.json          |  3 +--
 11 files changed, 45 insertions(+), 56 deletions(-)

diff --git a/qapi/control.json b/qapi/control.json
index 2788ce32e2f..ef63a8a261b 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/machine.json b/qapi/machine.json
index 276258d9e5c..2d5c7c36ad9 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -2002,13 +2002,13 @@
 
 ##
 # @query-cpu-model-comparison:
+#     Compares two CPU models, @modela and @modelb, returning how they
+#     compare in a specific configuration.
 #
-# 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.
+# 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).
@@ -2058,11 +2058,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
@@ -2130,11 +2129,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 a272e701385..8d3951ae429 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -1826,9 +1826,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
@@ -1945,8 +1945,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
@@ -1971,8 +1970,7 @@
 
 ##
 # @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
diff --git a/qapi/misc-arm.json b/qapi/misc-arm.json
index 8cb2ea77951..9b018b29e2c 100644
--- a/qapi/misc-arm.json
+++ b/qapi/misc-arm.json
@@ -28,9 +28,8 @@
 
 ##
 # @query-gic-capabilities:
-#
-# It will return a list of `GICCapability` objects that describe its
-# capability bits.
+#     Returns 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.
diff --git a/qapi/misc.json b/qapi/misc.json
index b62cabc2b79..b4bb8a662e6 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.
@@ -185,8 +184,7 @@
 
 ##
 # @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
diff --git a/qapi/net.json b/qapi/net.json
index d0bacb4dcfe..b0a15fd53e2 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/qdev.json b/qapi/qdev.json
index a35321d2fd1..f390354d68e 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -162,11 +162,10 @@
 
 ##
 # @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
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

[PATCH v2 09/10] 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 13981d7e69d..741c8165c06 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -843,9 +843,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 00a03e57b98..b18c6d94a38 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1629,9 +1629,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.
@@ -1890,8 +1890,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 v2 10/10] 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.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/block-export.json |  5 ++---
 qapi/crypto.json       |  3 +--
 qapi/machine.json      | 11 ++++-------
 qapi/net.json          | 34 +++++++++++++++-------------------
 qapi/qom.json          |  9 +++------
 5 files changed, 25 insertions(+), 37 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 7b4c80edae2..a8d753d360f 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 b18c6d94a38..1220116bf7d 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -684,9 +684,8 @@
 
 ##
 # @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.
@@ -760,8 +759,7 @@
 
 ##
 # @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.
@@ -926,8 +924,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/net.json b/qapi/net.json
index b0a15fd53e2..2a186a71b93 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -719,11 +719,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')
 #
@@ -750,11 +749,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
@@ -793,15 +791,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
@@ -838,10 +835,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..e67cd0cd54d 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

Re: [PATCH v2 02/10] qapi: convert/split intros for block-core.json commands

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/block-core.json | 126 +++++++++++++++++++------------------------
>  1 file changed, 55 insertions(+), 71 deletions(-)
>
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index 802a4af74ed..13981d7e69d 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -1556,8 +1556,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.
>  #
> @@ -1812,13 +1811,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.

The second paragraph refers to arguments.

For types, such text tends to be something we want to inline, and for
that, it needs to stay out of intro, and eventually move below the fold.

Not a concern for commands and events.  But we might want to do the same
just for consistency.

The hunk is acceptable as is.  I'm tracking

2. Review and improve doc comments where the intro refers to arguments /
members / features.

Splitting now would also be acceptable, as long as the split is trivial
enough to not slow us down.  You did that for block_resize above.

>  #
>  # Features:
>  #
> @@ -1883,9 +1881,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'.

Likewise, except a split doesn't look trivial.

>  #
>  # 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
> @@ -2510,16 +2507,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.

Again.

>  #
>  # Errors:
>  #     - If @node is not a valid block device, DeviceNotFound
> @@ -2865,8 +2861,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

Another trivial split.  Not noting these again.

> @@ -2977,8 +2972,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.
>  #
> @@ -3003,8 +2997,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
> @@ -3046,8 +3039,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.
> @@ -3079,8 +3071,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.
> @@ -3108,9 +3099,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
> @@ -3148,14 +3139,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.

Forward reference to an argument again.

>  #
>  # This command will refuse to operate on any job that has not yet
>  # reached its terminal state, CONCLUDED.  For jobs that make use of
> @@ -3177,11 +3167,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
> @@ -4917,14 +4906,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

This one affects rendered documentation.  Suggest to mention it in the
commit message, like the previous patch does.

> @@ -4996,9 +4984,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
> @@ -5881,15 +5868,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.
>  #
> @@ -5911,8 +5897,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
> @@ -5971,11 +5956,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.

Forward reference to an argument again.

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

In the interest of getting the job done: consider my commit message
suggestion, and leave the remainder for another day.

Re: [PATCH v2 03/10] qapi: convert/split intros for block commands

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

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

Consider mentioning how this affects rendered documentation:

1. blockdev-open-tray and blockdev-close-tray: first paragraph splits

2. block_set_io_throttle, nbd-server-add: Arguments: move up.

Re: [PATCH v2 04/10] qapi: convert/split intros for job.json commands

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

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

Consider mentioning how this affects rendered documentation: first
paragraph of job-dismiss splits.

Re: [PATCH v2 05/10] qapi: convert/split intros for misc-i386.json commands

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

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

Consider mentioning how this affects rendered documentation: query-sev's
Return: moves up.

Re: [PATCH v2 10/10] qapi: split intro sections for inlinable structs

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> 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.
>
> Signed-off-by: John Snow <jsnow@redhat.com>

Consider mentioning how this affects rendered documentation now:
MemoryBackendShmProperties and MemoryBackendEpcProperties member
descriptions move up some.

> ---
>  qapi/block-export.json |  5 ++---
>  qapi/crypto.json       |  3 +--
>  qapi/machine.json      | 11 ++++-------
>  qapi/net.json          | 34 +++++++++++++++-------------------
>  qapi/qom.json          |  9 +++------
>  5 files changed, 25 insertions(+), 37 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 7b4c80edae2..a8d753d360f 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 b18c6d94a38..1220116bf7d 100644
> --- a/qapi/machine.json
> +++ b/qapi/machine.json
> @@ -684,9 +684,8 @@
>  
>  ##
>  # @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.
> @@ -760,8 +759,7 @@
>  
>  ##
>  # @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.
> @@ -926,8 +924,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/net.json b/qapi/net.json
> index b0a15fd53e2..2a186a71b93 100644
> --- a/qapi/net.json
> +++ b/qapi/net.json
> @@ -719,11 +719,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.
>  #

This is an instructive example of a "split or keep in intro" decision
guided by contents: the second paragraph will likely not be useful when
inlined into Netdev, so you keep it in intro.

If the contents of the paragraph would be missed when the inliner elides
it, we'll need to figure out where to put it.  Not now.

>  # @vhostdev: path of vhost-vdpa device (default:'/dev/vhost-vdpa-0')
>  #
> @@ -750,11 +749,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.

Similar.

>  #
>  # @start-address: The starting IPv4 address to use for the interface.
>  #     Must be in the private IP range (RFC 1918).  Must be specified
> @@ -793,15 +791,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.

Similar.

>  #
>  # @start-address: The starting IPv4 address to use for the interface.
>  #     Must be in the private IP range (RFC 1918).  Must be specified
> @@ -838,10 +835,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.

Similar.

>  #
>  # @ifname: The name of the physical interface to be bridged.
>  #
> diff --git a/qapi/qom.json b/qapi/qom.json
> index 51af9485e6d..e67cd0cd54d 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
>  #

Re: [PATCH v2 09/10] qapi: split intro sections for data structs

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

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

Help me out, please: which notes exactly?

> 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 13981d7e69d..741c8165c06 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -843,9 +843,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.
>  #
   # Limitation: covers only syntactic aspects of QMP, i.e. stuff tagged
   # with feature 'deprecated' or 'unstable'.  We may want to extend it
   # to cover semantic aspects and CLI.
   #
   # Limitation: deprecated-output policy @hide is not implemented for
   # enumeration values.  They behave the same as with policy @accept.

"This is intended for" caught my eyes.  Inlining it feels problematic.
For starters, how will "this" be interpreted in the new context?

Fortunately, this won't be inlined any time soon: it's used just as
argument of -compat, and the CLI isn't QAPIfied.

Similar difficulties can arise whenever we inline more than just member
descriptions.  Avoiding them now feels impractical; we'll have to read
the texts in the contexts where the inliner puts them.  I see a lot of
proofreading and doc editing in our future.

> diff --git a/qapi/machine.json b/qapi/machine.json
> index 00a03e57b98..b18c6d94a38 100644
> --- a/qapi/machine.json
> +++ b/qapi/machine.json
> @@ -1629,9 +1629,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.
> @@ -1890,8 +1890,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

Re: [PATCH v2 06/10] qapi: convert/split intros for commands

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> This patch converts or splits intro sections for commands with more
> than one paragraph of text.
>
> Signed-off-by: John Snow <jsnow@redhat.com>

Consider mentioning how the splits affect rendered documentation:
netdev_add's arguments description moves up.

> ---
>  qapi/control.json     |  3 +--
>  qapi/introspect.json  | 16 ++++++++--------
>  qapi/machine.json     | 31 +++++++++++++++----------------
>  qapi/migration.json   | 12 +++++-------
>  qapi/misc-arm.json    |  5 ++---
>  qapi/misc.json        |  8 +++-----
>  qapi/net.json         |  3 +--
>  qapi/qdev.json        |  9 ++++-----
>  qapi/stats.json       |  5 ++---
>  qapi/transaction.json |  6 +++---
>  qapi/ui.json          |  3 +--
>  11 files changed, 45 insertions(+), 56 deletions(-)
>
> diff --git a/qapi/control.json b/qapi/control.json
> index 2788ce32e2f..ef63a8a261b 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.

You delete "However".  Fine with me, but I didn't anticipate it based on
the commit message.  Easy enough to fix: mention it there.

>  #
>  # Furthermore, while we strive to keep the QMP wire format
>  # backwards-compatible across QEMU versions, the introspection output
> diff --git a/qapi/machine.json b/qapi/machine.json
> index 276258d9e5c..2d5c7c36ad9 100644
> --- a/qapi/machine.json
> +++ b/qapi/machine.json
> @@ -2002,13 +2002,13 @@
>  
>  ##
>  # @query-cpu-model-comparison:
> +#     Compares two CPU models, @modela and @modelb, returning how they
> +#     compare in a specific configuration.
>  #
> -# 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.
> +# The results indicates how both models compare regarding runnability.

Not this patch's job: either "result indicates" or "results indicate".

We should feed the entire manual to a mechanized proofreader at some
point.

> +# 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).
> @@ -2058,11 +2058,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
> @@ -2130,11 +2129,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 a272e701385..8d3951ae429 100644
> --- a/qapi/migration.json
> +++ b/qapi/migration.json
> @@ -1826,9 +1826,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
> @@ -1945,8 +1945,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
> @@ -1971,8 +1970,7 @@
>  
>  ##
>  # @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
> diff --git a/qapi/misc-arm.json b/qapi/misc-arm.json
> index 8cb2ea77951..9b018b29e2c 100644
> --- a/qapi/misc-arm.json
> +++ b/qapi/misc-arm.json
> @@ -28,9 +28,8 @@
>  
>  ##
>  # @query-gic-capabilities:
> -#
> -# It will return a list of `GICCapability` objects that describe its
> -# capability bits.
> +#     Returns a list of `GICCapability` objects that describe its
> +#     capability bits.

You switch to imperative mood.  Good, but I think it's best left for
  later.  I'm tracking it as

4. Consistently use imperative mood for command intros.

>  #
>  # On non-ARM targets this command will report an error as the GIC
>  # technology is not applicable.
> diff --git a/qapi/misc.json b/qapi/misc.json
> index b62cabc2b79..b4bb8a662e6 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.
> @@ -185,8 +184,7 @@
>  
>  ##
>  # @x-exit-preconfig:
> -#
> -# Exit from "preconfig" state
> +#     Exit from "preconfig" state.

You add a period.  Good, but I think it's best left for later.  I'm
tracking it as

7. Clean up intros to consist of sentences.  Sentences start with a
capital letter and end with a period.

>  #
>  # This command makes QEMU exit the preconfig state and proceed with VM
>  # initialization using configuration data provided on the command line
> diff --git a/qapi/net.json b/qapi/net.json
> index d0bacb4dcfe..b0a15fd53e2 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/qdev.json b/qapi/qdev.json
> index a35321d2fd1..f390354d68e 100644
> --- a/qapi/qdev.json
> +++ b/qapi/qdev.json
> @@ -162,11 +162,10 @@
>  
>  ##
>  # @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
> 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

Re: [PATCH v2 04/10] qapi: convert/split intros for job.json commands

[John Snow]

On Wed, Sep 23, 2026 at 5:20 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> John Snow <jsnow@redhat.com> writes:
>
> > Signed-off-by: John Snow <jsnow@redhat.com>
>
> Consider mentioning how this affects rendered documentation: first
> paragraph of job-dismiss splits.

ACK

Re: [PATCH v2 09/10] qapi: split intro sections for data structs

[John Snow]

On Wed, Sep 23, 2026 at 6:48 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> John Snow <jsnow@redhat.com> writes:
>
> > 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.
>
> Help me out, please: which notes exactly?

*cough* I am drowning in rebases. Sorry, leftover from an earlier revision.

Removing this paragraph, but what it *was* referring to was the fact
that I left "plaintext" sections in place instead of relocating them,
and that the splits I made were effectively arbitrary based on vibes.



>
> > 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 13981d7e69d..741c8165c06 100644
> > --- a/qapi/block-core.json
> > +++ b/qapi/block-core.json
> > @@ -843,9 +843,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.
> >  #
>    # Limitation: covers only syntactic aspects of QMP, i.e. stuff tagged
>    # with feature 'deprecated' or 'unstable'.  We may want to extend it
>    # to cover semantic aspects and CLI.
>    #
>    # Limitation: deprecated-output policy @hide is not implemented for
>    # enumeration values.  They behave the same as with policy @accept.
>
> "This is intended for" caught my eyes.  Inlining it feels problematic.
> For starters, how will "this" be interpreted in the new context?
>
> Fortunately, this won't be inlined any time soon: it's used just as
> argument of -compat, and the CLI isn't QAPIfied.
>
> Similar difficulties can arise whenever we inline more than just member
> descriptions.  Avoiding them now feels impractical; we'll have to read
> the texts in the contexts where the inliner puts them.  I see a lot of
> proofreading and doc editing in our future.

Will reshuffle this bit.

Yes, there needs to be a doc review push - this is more than I can
handle on my own, but if each maintainer could be bribed to review
*just* their own module, we could probably make sure we hit all of the
glaring problems...

>
> > diff --git a/qapi/machine.json b/qapi/machine.json
> > index 00a03e57b98..b18c6d94a38 100644
> > --- a/qapi/machine.json
> > +++ b/qapi/machine.json
> > @@ -1629,9 +1629,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.
> > @@ -1890,8 +1890,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
>

Re: [PATCH v2 02/10] qapi: convert/split intros for block-core.json commands

[John Snow]

On Wed, Sep 23, 2026 at 4:50 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> John Snow <jsnow@redhat.com> writes:
>
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> >  qapi/block-core.json | 126 +++++++++++++++++++------------------------
> >  1 file changed, 55 insertions(+), 71 deletions(-)
> >
> > diff --git a/qapi/block-core.json b/qapi/block-core.json
> > index 802a4af74ed..13981d7e69d 100644
> > --- a/qapi/block-core.json
> > +++ b/qapi/block-core.json
> > @@ -1556,8 +1556,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.
> >  #
> > @@ -1812,13 +1811,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.
>
> The second paragraph refers to arguments.
>
> For types, such text tends to be something we want to inline, and for
> that, it needs to stay out of intro, and eventually move below the fold.
>
> Not a concern for commands and events.  But we might want to do the same
> just for consistency.

I agree; it's not always going to be clear at a glance which intros
will make it into the final documentation, and which won't. I think
people will learn over time, but consistency is a good thing as the
copy-paste-templaters will have good examples to follow.

>
> The hunk is acceptable as is.  I'm tracking
>
> 2. Review and improve doc comments where the intro refers to arguments /
> members / features.
>
> Splitting now would also be acceptable, as long as the split is trivial
> enough to not slow us down.  You did that for block_resize above.

Well, we'll have to sort it out sooner or later, so...

Anyway.

Are forward references really that bad? We obviously don't want to go
overboard, but sometimes - especially for commands with lots of
branches and features - highlighting the core functionality of the
command with reference to specific members is not really a bad thing.
It can help suggest what the "important" arguments are for the block
to follow.

In this case I actually do think it makes sense to appear above the
fold, almost like a cover letter, to help guide reading of the details
that follow.

It makes sense to look at any intros that refer to arguments and
wonder in which section it is more appropriate, but in this case I do
think it is entirely appropriate.

>
> >  #
> >  # Features:
> >  #
> > @@ -1883,9 +1881,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'.
>
> Likewise, except a split doesn't look trivial.

Candidate for a rewrite. Not for this series.

>
> >  #
> >  # 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
> > @@ -2510,16 +2507,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.
>
> Again.

Definitely another rewrite candidate. I wonder who wrote this one?

(Ah,)

Anyway, I do volunteer to do a series reviewing bitmaps, because I'd
like to tie the standalone bitmaps doc and the QAPI documentation
together more holistically with the new cross-reference features.

I think for now we leave this one alone for now and revisit post-inliner.

>
> >  #
> >  # Errors:
> >  #     - If @node is not a valid block device, DeviceNotFound
> > @@ -2865,8 +2861,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
>
> Another trivial split.  Not noting these again.

Is that good or bad for the purposes of this review?

I figured the intro here is a succinct summary, but the second
paragraph gives additional insight into the implementation, so it
seemed appropriate.

The first time you said "trivial split" in this series, it seemed to
me to intuit a place where you'd like a split, but in this case it's
where I already made one. Not sure what the action item is.

>
> > @@ -2977,8 +2972,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.
> >  #
> > @@ -3003,8 +2997,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
> > @@ -3046,8 +3039,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.
> > @@ -3079,8 +3071,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.
> > @@ -3108,9 +3099,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
> > @@ -3148,14 +3139,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.
>
> Forward reference to an argument again.

Candidate for a prose rewrite to more easily distinguish introduction
from details. Something for later? Since I also had a hand in the job
impl, I feel equipped to handle these along with bitmaps.

>
> >  #
> >  # This command will refuse to operate on any job that has not yet
> >  # reached its terminal state, CONCLUDED.  For jobs that make use of
> > @@ -3177,11 +3167,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
> > @@ -4917,14 +4906,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
>
> This one affects rendered documentation.  Suggest to mention it in the
> commit message, like the previous patch does.

Sure. I didn't really mention them up to this point because we had
been avoiding any changes, but implicitly this series is about
allowing and making such changes. I didn't actually audit specifically
WHICH ones cause rendering changes, I just knew that it would happen
for some.

Do you want an explicit accounting of which ones do, or is it enough
to say "This might change rendering in cases where a new split is
introduced" ...?

>
> > @@ -4996,9 +4984,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
> > @@ -5881,15 +5868,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.
> >  #
> > @@ -5911,8 +5897,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
> > @@ -5971,11 +5956,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.
>
> Forward reference to an argument again.

Would need a rewrite to avoid discussing implementation in the
summary, so IMO it's a task for later. My goal right now is generally
just to accomplish the split in some semi-reasonable way without an
obvious degradation in quality of what is available to the end user
without getting bogged down in the mires of prose rewrites.

Fixing these sorts of things right now is probably well beyond the
scope I can afford, currently.

>
> > -#
> > -# 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
> >  #
>
> In the interest of getting the job done: consider my commit message
> suggestion, and leave the remainder for another day.

I think I agree, so long as the splits I chose here are "acceptable
enough" to not inhibit the inliner work, i.e. the docs are not really
tangibly worse for having done it and the prose rewrites can be
"if/when" improvements.

Re: [PATCH v2 02/10] qapi: convert/split intros for block-core.json commands

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> On Wed, Sep 23, 2026 at 4:50 AM Markus Armbruster <armbru@redhat.com> wrote:
>>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > Signed-off-by: John Snow <jsnow@redhat.com>
>> > ---
>> >  qapi/block-core.json | 126 +++++++++++++++++++------------------------
>> >  1 file changed, 55 insertions(+), 71 deletions(-)
>> >
>> > diff --git a/qapi/block-core.json b/qapi/block-core.json
>> > index 802a4af74ed..13981d7e69d 100644
>> > --- a/qapi/block-core.json
>> > +++ b/qapi/block-core.json
>> > @@ -1556,8 +1556,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.
>> >  #
>> > @@ -1812,13 +1811,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.
>>
>> The second paragraph refers to arguments.
>>
>> For types, such text tends to be something we want to inline, and for
>> that, it needs to stay out of intro, and eventually move below the fold.
>>
>> Not a concern for commands and events.  But we might want to do the same
>> just for consistency.
>
> I agree; it's not always going to be clear at a glance which intros
> will make it into the final documentation, and which won't. I think
> people will learn over time, but consistency is a good thing as the
> copy-paste-templaters will have good examples to follow.

Yes.  People with ordinary general programming skills should be able to
write passable schema bits by imitating what's already there.  If they
need to study up on QAPI first, we failed.

>> The hunk is acceptable as is.  I'm tracking
>>
>> 2. Review and improve doc comments where the intro refers to arguments /
>> members / features.
>>
>> Splitting now would also be acceptable, as long as the split is trivial
>> enough to not slow us down.  You did that for block_resize above.
>
> Well, we'll have to sort it out sooner or later, so...

Sitting on ~100 conversion patches I'd prefer to merge only when the
conversion job is complete makes me take a rather dim view on "we need
to do this at some point anyway, so let's get it over with."

> Anyway.
>
> Are forward references really that bad? We obviously don't want to go
> overboard, but sometimes - especially for commands with lots of
> branches and features - highlighting the core functionality of the
> command with reference to specific members is not really a bad thing.
> It can help suggest what the "important" arguments are for the block
> to follow.
>
> In this case I actually do think it makes sense to appear above the
> fold, almost like a cover letter, to help guide reading of the details
> that follow.
>
> It makes sense to look at any intros that refer to arguments and
> wonder in which section it is more appropriate, but in this case I do
> think it is entirely appropriate.

Valid points.

We must keep type intros "pure" for the inliner's sake: just a terse
statement of purpose, no more.

This does not apply to commands and events.  We may want to keep them
"pure" anyway to promote the habit of writing "pure" intros, and maybe
for the occasional case of factoring out arguments into a type.

Note "may want".  I don't have a strong opinion, yet.  I hope to develop
one during the inliner merge.

>> >  #
>> >  # Features:
>> >  #
>> > @@ -1883,9 +1881,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'.
>>
>> Likewise, except a split doesn't look trivial.
>
> Candidate for a rewrite. Not for this series.

Yes.

>> >  #
>> >  # 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
>> > @@ -2510,16 +2507,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.
>>
>> Again.
>
> Definitely another rewrite candidate. I wonder who wrote this one?
>
> (Ah,)

*Chuckle*

> Anyway, I do volunteer to do a series reviewing bitmaps, because I'd
> like to tie the standalone bitmaps doc and the QAPI documentation
> together more holistically with the new cross-reference features.
>
> I think for now we leave this one alone for now and revisit post-inliner.

Definitely not now.

>> >  #
>> >  # Errors:
>> >  #     - If @node is not a valid block device, DeviceNotFound
>> > @@ -2865,8 +2861,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
>>
>> Another trivial split.  Not noting these again.
>
> Is that good or bad for the purposes of this review?
>
> I figured the intro here is a succinct summary, but the second
> paragraph gives additional insight into the implementation, so it
> seemed appropriate.
>
> The first time you said "trivial split" in this series, it seemed to
> me to intuit a place where you'd like a split, but in this case it's
> where I already made one. Not sure what the action item is.

My apologies for lack of clarity.  This one looks fine to me, and so do
the trivial splits "not noted again".

>>
>> > @@ -2977,8 +2972,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.
>> >  #
>> > @@ -3003,8 +2997,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
>> > @@ -3046,8 +3039,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.
>> > @@ -3079,8 +3071,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.
>> > @@ -3108,9 +3099,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
>> > @@ -3148,14 +3139,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.
>>
>> Forward reference to an argument again.
>
> Candidate for a prose rewrite to more easily distinguish introduction
> from details. Something for later? Since I also had a hand in the job
> impl, I feel equipped to handle these along with bitmaps.

Yes, later.

>> >  #
>> >  # This command will refuse to operate on any job that has not yet
>> >  # reached its terminal state, CONCLUDED.  For jobs that make use of
>> > @@ -3177,11 +3167,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
>> > @@ -4917,14 +4906,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
>>
>> This one affects rendered documentation.  Suggest to mention it in the
>> commit message, like the previous patch does.
>
> Sure. I didn't really mention them up to this point because we had
> been avoiding any changes, but implicitly this series is about
> allowing and making such changes. I didn't actually audit specifically
> WHICH ones cause rendering changes, I just knew that it would happen
> for some.
>
> Do you want an explicit accounting of which ones do, or is it enough
> to say "This might change rendering in cases where a new split is
> introduced" ...?

I like output changed mentioned, because they're commonly invisible in
the patch.  I've been flagging all of them in review.

>> > @@ -4996,9 +4984,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
>> > @@ -5881,15 +5868,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.
>> >  #
>> > @@ -5911,8 +5897,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
>> > @@ -5971,11 +5956,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.
>>
>> Forward reference to an argument again.
>
> Would need a rewrite to avoid discussing implementation in the
> summary, so IMO it's a task for later. My goal right now is generally
> just to accomplish the split in some semi-reasonable way without an
> obvious degradation in quality of what is available to the end user
> without getting bogged down in the mires of prose rewrites.

Broken record: we cannot afford perfect splits now; we need to get the
syntax conversion job done.

> Fixing these sorts of things right now is probably well beyond the
> scope I can afford, currently.

Fair.

>> > -#
>> > -# 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
>> >  #
>>
>> In the interest of getting the job done: consider my commit message
>> suggestion, and leave the remainder for another day.
>
> I think I agree, so long as the splits I chose here are "acceptable
> enough" to not inhibit the inliner work, i.e. the docs are not really
> tangibly worse for having done it and the prose rewrites can be
> "if/when" improvements.

I believe they don't make the inliner work any harder.  That's good
enough for me.

Re: [PATCH v2 03/10] qapi: convert/split intros for block commands

[Eric Blake]

On Wed, Sep 23, 2026 at 11:17:58AM +0200, Markus Armbruster wrote:
> John Snow <jsnow@redhat.com> writes:
> 
> > Signed-off-by: John Snow <jsnow@redhat.com>
> 
> Consider mentioning how this affects rendered documentation:
> 
> 1. blockdev-open-tray and blockdev-close-tray: first paragraph splits
> 
> 2. block_set_io_throttle, nbd-server-add: Arguments: move up.

I'm liking this series, but also the suggestions of documenting the
known impacts. At this point, I'm trusting Markus' review rather than
diving in deep myself, but you're welcome to add:

Acked-by: Eric Blake <eblake@redhat.com>

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization:  qemu.org | libguestfs.org

Re: [PATCH v2 03/10] qapi: convert/split intros for block commands

[John Snow]

On Mon, Sep 28, 2026 at 10:33 AM Eric Blake <eblake@redhat.com> wrote:
>
> On Wed, Sep 23, 2026 at 11:17:58AM +0200, Markus Armbruster wrote:
> > John Snow <jsnow@redhat.com> writes:
> >
> > > Signed-off-by: John Snow <jsnow@redhat.com>
> >
> > Consider mentioning how this affects rendered documentation:
> >
> > 1. blockdev-open-tray and blockdev-close-tray: first paragraph splits
> >
> > 2. block_set_io_throttle, nbd-server-add: Arguments: move up.
>
> I'm liking this series, but also the suggestions of documenting the
> known impacts. At this point, I'm trusting Markus' review rather than
> diving in deep myself, but you're welcome to add:
>
> Acked-by: Eric Blake <eblake@redhat.com>

I'll admit that I have been somewhat lacking in providing a
comprehensive analysis in each cover letter as we have been doing this
conversion rather piecemeal in order to make it more palatable on the
list, but here's the best, shortest synopsis I can hope to give you:

(A) In order to define a point in the documentation where we should
insert auto-generated documentation (for members, returns, etc) we are
pivoting towards a strict ordering of sections:

1. Intro
2. Members
3. Returns
4. Errors
5. Features
6. Details
7. Since

With this goal in mind, the "Intro" will always be up at the very top,
but "Details" - the unindented portions in this series - are
ultimately fated to get sifted to the bottom. If you consult the
rendered QMP documentation - for example `block-dirty-bitmap-add`:
https://www.qemu.org/docs/master/interop/qemu-qmp-ref.html#command-QMP-block-core.block-dirty-bitmap-add

The stuff that appears in the middle - Arguments and Errors - always
forms a two-column table sort of layout.

Anything that appears above it I have been calling "above the fold" -
and that's always the Introduction text, now.

Anything that appears below I have been informally calling "below the
fold" - and that's always details text, now.

So with this in mind, stuff I indent will go "above" and stuff I do
not will go "below". Simple enough.

(B) The tricky part: We are still pursuing the documentation inliner,
which means that for block-dirty-bitmap-add, the arguments we
"inherit" from the "BlockDirtyBitmap" structure will be displayed
"inline" as if they were defined locally for this command. When we
inline documentation from another definition/entity, we need to know
where and how to splice the documentation together to form a coherent
document.

What Markus and I decided on was to *drop* the intro from any inlined
documentation. For this reason, delineating the Intro from the Details
becomes very important: the Intro text will not travel with the
inlined arguments.

With this in mind, the splits we are creating here become very
important for structures specifically, as their intro text will get
dropped on the floor when it is rendered in an inlined context. The
split for commands, enums, etc., is less important because there is
never any circumstance where we would drop the intro on the floor.

>
> --
> Eric Blake, Principal Software Engineer
> Red Hat, Inc.
> Virtualization:  qemu.org | libguestfs.org
>