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

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

[John Snow]

This series is the last batch of intro conversions.

V2:
 - Address review comments
 - Adjust commit messages, add S-O-B

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        |   5 +-
 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   |   7 +--
 qapi/ui.json            |   8 +--
 21 files changed, 193 insertions(+), 254 deletions(-)

-- 
2.55.0

[PATCH v3 01/10] qapi: split intro for HV_BALLOON_STATUS_REPORT

[John Snow]

This changes the rendering for this event by adding a new insertion
point right after the introductory paragraph, before the
".. note::".

Because this event features auto-inserted member documentation ("The
members of "HvBalloonInfo"), creating this new split point changes the
rendered documentation - the ".. note::" now appears below the
generated member documentation instead of above it.

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

diff --git a/qapi/machine.json b/qapi/machine.json
index 89e7acdc1ac..b5d4eb8db95 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1215,9 +1215,8 @@
 
 ##
 # @HV_BALLOON_STATUS_REPORT:
-#
-# Emitted when the hv-balloon driver receives a "STATUS" message from
-# the guest.
+#     Emitted when the hv-balloon driver receives a "STATUS" message
+#     from the guest.
 #
 # .. note:: This event is rate-limited.
 #
-- 
2.55.0

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

[John Snow]

Convert, or split off, intro sections for commands defined in
block-core.json. In general, this does not currently impact the way
these commands are rendered, except:

1. blockdev-reopen sees its arguments shit up to just below the
   formalized introductory section.

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 v3 03/10] qapi: convert/split intros for block commands

[John Snow]

Convert, or split off, intro sections for commands defined in
block.json and block-export.json. In general, this does not currently
impact the way these commands are rendered, except:

1. blockdev-open-tray and blockdev-close-tray see their opening
   paragraphs split apart, which is reflected in the rendered output,
   and

2. block_set_io_throttle and nbd-server-add see their argument
   definitions move up to just below the formalized introductory
   section.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/block-export.json |  3 +--
 qapi/block.json        | 33 ++++++++++++++++-----------------
 2 files changed, 17 insertions(+), 19 deletions(-)

diff --git a/qapi/block-export.json b/qapi/block-export.json
index e9f7e72c8ee..77459f6321b 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -235,8 +235,7 @@
 
 ##
 # @nbd-server-add:
-#
-# Export a block node to QEMU's embedded NBD server.
+#     Export a block node to QEMU's embedded NBD server.
 #
 # The export name will be used as the id for the resulting block
 # export.
diff --git a/qapi/block.json b/qapi/block.json
index 53f0a623afa..0a88d405a26 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -128,11 +128,12 @@
 
 ##
 # @blockdev-open-tray:
+#     Opens a block device's tray.
 #
-# Opens a block device's tray.  If there is a block driver state tree
-# inserted as a medium, it will become inaccessible to the guest (but
-# it will remain associated to the block device, so closing the tray
-# will make it accessible again).
+# If there is a block driver state tree inserted as a medium, it will
+# become inaccessible to the guest (but it will remain associated to
+# the block device, so closing the tray will make it accessible
+# again).
 #
 # If the tray was already open before, this will be a no-op.
 #
@@ -181,10 +182,11 @@
 
 ##
 # @blockdev-close-tray:
+#     Closes a block device's tray.
 #
-# Closes a block device's tray.  If there is a block driver state tree
-# associated with the block device (which is currently ejected), that
-# tree will be loaded as the medium.
+# If there is a block driver state tree associated with the block
+# device (which is currently ejected), that tree will be loaded as the
+# medium.
 #
 # If the tray was already closed before, this will be a no-op.
 #
@@ -218,13 +220,12 @@
 
 ##
 # @blockdev-remove-medium:
+#     Removes a medium (a block driver state tree) from a block
+#     device.  That block device's tray must currently be open
+#     (unless there is no attached guest device).
 #
-# Removes a medium (a block driver state tree) from a block device.
-# That block device's tray must currently be open (unless there is no
-# attached guest device).
-#
-# If the tray is open and there is no medium inserted, this will be a
-# no-op.
+# If the tray is open and there is no medium inserted, this will
+# be a no-op.
 #
 # @id: The name or QOM path of the guest device
 #
@@ -429,8 +430,7 @@
 
 ##
 # @block_set_io_throttle:
-#
-# Change I/O throttle limits for a block drive.
+#     Change I/O throttle limits for a block drive.
 #
 # Since QEMU 2.4, each device with I/O limits is member of a throttle
 # group.
@@ -504,8 +504,7 @@
 
 ##
 # @block-latency-histogram-set:
-#
-# Manage read, write and flush latency histograms for the device.
+#     Manage read, write and flush latency histograms for the device.
 #
 # If only @id parameter is specified, remove all present latency
 # histograms for the device.  Otherwise, add/reset some of (or all)
-- 
2.55.0

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

[John Snow]

Convert or split apart the existing intro for commands in job.json
into introduction and details sections. The introduction is indented,
remaining plaintext/details paragraphs are not.

@job-dismiss has its text split apart a little more aggressively to
help the documentation read more smoothly in the rendered version.

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 v3 05/10] qapi: convert/split intros for misc-i386.json commands

[John Snow]

Convert or split apart the existing intro for commands in
misc-i386.json into introduction and details sections. The
introduction is indented, remaining plaintext/details paragraphs are
not.

For commands that have automatically generated documentation inserted
at parse time, these new split points serve as the new insertion
point. This affects the rendered documentation for `query-sev` in
particular, whose "Returns:" documentation is pushed upwards.

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

diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json
index 78ec9aec647..6e0ab46b8ea 100644
--- a/qapi/misc-i386.json
+++ b/qapi/misc-i386.json
@@ -5,10 +5,9 @@
 
 ##
 # @rtc-reset-reinjection:
-#
-# Reset the RTC interrupt reinjection backlog.  Can be used if another
-# mechanism to synchronize guest time is in effect, for example QEMU
-# guest agent's `guest-set-time` command.
+#     Reset the RTC interrupt reinjection backlog.  Can be used if
+#     another mechanism to synchronize guest time is in effect, for
+#     example QEMU guest agent's `guest-set-time` command.
 #
 # Use of this command is only applicable for x86 machines with an RTC,
 # and on other machines will silently return without performing any
@@ -119,8 +118,7 @@
 
 ##
 # @query-sev:
-#
-# Return information about SEV/SEV-ES/SEV-SNP.
+#     Return information about SEV/SEV-ES/SEV-SNP.
 #
 # If unavailable due to an incompatible configuration the returned
 # @enabled field is set to 'false' and the state of all other fields
@@ -149,8 +147,7 @@
 
 ##
 # @query-sev-launch-measure:
-#
-# Query the SEV/SEV-ES guest launch information.
+#     Query the SEV/SEV-ES guest launch information.
 #
 # This is only valid on x86 machines configured with KVM and the
 # 'sev-guest' confidential virtualization object.  The launch
@@ -199,8 +196,7 @@
 
 ##
 # @query-sev-capabilities:
-#
-# Get SEV capabilities.
+#     Get SEV capabilities.
 #
 # This is only supported on AMD X86 platforms with KVM enabled.
 #
@@ -220,8 +216,7 @@
 
 ##
 # @sev-inject-launch-secret:
-#
-# Inject a secret blob into a SEV/SEV-ES guest's memory.
+#     Inject a secret blob into a SEV/SEV-ES guest's memory.
 #
 # This is only valid on x86 machines configured with KVM and the
 # 'sev-guest' confidential virtualization object.  SEV-SNP guests do
@@ -257,8 +252,7 @@
 
 ##
 # @query-sev-attestation-report:
-#
-# Get the SEV attestation report.
+#     Get the SEV attestation report.
 #
 # This is only valid on x86 machines configured with KVM and the
 # 'sev-guest' confidential virtualization object.  The attestation
-- 
2.55.0

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

[John Snow]

Convert or split apart the existing intro for any remaining commands
in the QAPI schema into introduction and details sections. The
introduction is indented, remaining plaintext/details paragraphs
are not.

For commands that have automatically generated documentation inserted
at parse time, these new split points serve as the new insertion
point. This affects the rendered documentation for `netdev_add` in
particular, whose arguments descriptions are pushed upwards.

Minor rephrasings are applied for `query-qmp-schema` to help
the split flow better in rendered documentation.

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 |  7 +++----
 qapi/ui.json          |  3 +--
 11 files changed, 45 insertions(+), 57 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 b5d4eb8db95..e9584f91666 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -2007,13 +2007,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).
@@ -2063,11 +2063,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
@@ -2135,11 +2134,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..70859b2c37d 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.
+#     It will return a list of `GICCapability` objects that describe
+#     its capability bits.
 #
 # On non-ARM targets this command will report an error as the GIC
 # technology is not applicable.
diff --git a/qapi/misc.json b/qapi/misc.json
index b62cabc2b79..4469e44d057 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 81d1ab1c2ff..3541dd7cada 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..daecf843c90 100644
--- a/qapi/transaction.json
+++ b/qapi/transaction.json
@@ -197,10 +197,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 v3 07/10] qapi: convert/split intros for enums

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/machine.json | 22 ++++++++++------------
 qapi/ui.json      |  5 ++---
 2 files changed, 12 insertions(+), 15 deletions(-)

diff --git a/qapi/machine.json b/qapi/machine.json
index e9584f91666..75cbeca185f 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -641,9 +641,9 @@
 
 ##
 # @HmatLBMemoryHierarchy:
-#
-# The memory hierarchy in the System Locality Latency and Bandwidth
-# Information Structure of HMAT (Heterogeneous Memory Attribute Table)
+#     The memory hierarchy in the System Locality Latency and
+#     Bandwidth Information Structure of HMAT (Heterogeneous Memory
+#     Attribute Table)
 #
 # For more information about `HmatLBMemoryHierarchy`, see chapter
 # 5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec.
@@ -663,9 +663,9 @@
 
 ##
 # @HmatLBDataType:
-#
-# Data type in the System Locality Latency and Bandwidth Information
-# Structure of HMAT (Heterogeneous Memory Attribute Table)
+#     Data type in the System Locality Latency and Bandwidth
+#     Information Structure of HMAT (Heterogeneous Memory Attribute
+#     Table)
 #
 # For more information about `HmatLBDataType`, see chapter 5.2.27.4:
 # Table 5-146: Field "Data Type" of ACPI 6.3 spec.
@@ -726,9 +726,8 @@
 
 ##
 # @HmatCacheAssociativity:
-#
-# Cache associativity in the Memory Side Cache Information Structure
-# of HMAT
+#     Cache associativity in the Memory Side Cache Information
+#     Structure of HMAT
 #
 # For more information of `HmatCacheAssociativity`, see chapter
 # 5.2.27.5: Table 5-147 of ACPI 6.3 spec.
@@ -747,9 +746,8 @@
 
 ##
 # @HmatCacheWritePolicy:
-#
-# Cache write policy in the Memory Side Cache Information Structure of
-# HMAT
+#     Cache write policy in the Memory Side Cache Information
+#     Structure of HMAT
 #
 # For more information of `HmatCacheWritePolicy`, see chapter
 # 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
diff --git a/qapi/ui.json b/qapi/ui.json
index 73ee2cb2056..9e3e80a3d70 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -814,10 +814,9 @@
 
 ##
 # @QKeyCode:
+#     An enumeration of key name.
 #
-# An enumeration of key name.
-#
-# This is used by the `send-key` command.
+#     This is used by the `send-key` command.
 #
 # @unmapped: since 2.0
 #
-- 
2.55.0

[PATCH v3 08/10] qapi: split intro sections for events

[John Snow]

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

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

[PATCH v3 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 (currently) uses as a data type to describe its own
arguments or as a branch of a union: i.e. they are not currently
eligible to be 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.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/acpi.json       | 3 +--
 qapi/block-core.json | 5 ++---
 qapi/compat.json     | 5 ++---
 qapi/machine.json    | 9 ++++-----
 4 files changed, 9 insertions(+), 13 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 a512c77ffd8..0f90ea1f524 100644
--- a/qapi/compat.json
+++ b/qapi/compat.json
@@ -53,10 +53,9 @@
 
 ##
 # @CompatPolicy:
+#     Policy for handling deprecated management interfaces.
 #
-# Policy for handling deprecated management interfaces.
-#
-# This is intended for testing users of the 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
diff --git a/qapi/machine.json b/qapi/machine.json
index 75cbeca185f..d09424b8701 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1634,9 +1634,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.
@@ -1895,8 +1895,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 v3 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 left behind
when inlined into other contexts, but will still display the intro
section on standalone documentation for these types.

In general, this patch does not change how the rendered documentation
currently looks, except:

1. MemoryBackendShmProperties and MemoryBackendEpcProperties see their
   member descriptions move upwards to just below their formalized
   introductory sections.

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 d09424b8701..9b145c635ba 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -690,9 +690,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.
@@ -766,8 +765,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.
@@ -932,8 +930,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 3541dd7cada..f0312dfb714 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 59e523e3bfe..e03ede34421 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -465,8 +465,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.
@@ -765,8 +764,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.
@@ -780,8 +778,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 v3 02/10] qapi: convert/split intros for block-core.json commands

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> Convert, or split off, intro sections for commands defined in
> block-core.json. In general, this does not currently impact the way

Suggest to scratch "In general".

> these commands are rendered, except:
>
> 1. blockdev-reopen sees its arguments shit up to just below the

I trust you meant "shift" ;)

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

Happy to adjust commit messages without a respin.

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

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> Convert, or split off, intro sections for commands defined in
> block.json and block-export.json. In general, this does not currently

Suggest to scratch "In general".

> impact the way these commands are rendered, except:
>
> 1. blockdev-open-tray and blockdev-close-tray see their opening
>    paragraphs split apart, which is reflected in the rendered output,
>    and
>
> 2. block_set_io_throttle and nbd-server-add see their argument
>    definitions move up to just below the formalized introductory
>    section.
>
> Signed-off-by: John Snow <jsnow@redhat.com>

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

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> Convert or split apart the existing intro for any remaining commands
> in the QAPI schema into introduction and details sections. The
> introduction is indented, remaining plaintext/details paragraphs
> are not.
>
> For commands that have automatically generated documentation inserted
> at parse time, these new split points serve as the new insertion
> point. This affects the rendered documentation for `netdev_add` in
> particular, whose arguments descriptions are pushed upwards.

Missing: query-stats arguments and query-gic-capabilities "Return:" move
up.

>
> Minor rephrasings are applied for `query-qmp-schema` to help
> the split flow better in rendered documentation.
>
> Signed-off-by: John Snow <jsnow@redhat.com>

Happy to adjust commit messages without a respin.

Re: [PATCH v3 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 left behind
> when inlined into other contexts, but will still display the intro
> section on standalone documentation for these types.
>
> In general, this patch does not change how the rendered documentation
> currently looks, except:

Suggest to scratch "In general".

> 1. MemoryBackendShmProperties and MemoryBackendEpcProperties see their
>    member descriptions move upwards to just below their formalized
>    introductory sections.
>
> Signed-off-by: John Snow <jsnow@redhat.com>

Happy to adjust commit messages without a respin.

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

[Markus Armbruster]

I suggested a couple of commit message improvements.  Happy to make the
ones you like without a respin.

Series
Reviewed-by: Markus Armbruster <armbru@redhat.com>

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

[John Snow]

[-- Attachment #1: Type: text/plain, Size: 658 bytes --]

On Tue, Sep 29, 2026, 2:00 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > Convert, or split off, intro sections for commands defined in
> > block-core.json. In general, this does not currently impact the way
>
> Suggest to scratch "In general".
>
> > these commands are rendered, except:
> >
> > 1. blockdev-reopen sees its arguments shit up to just below the
>
> I trust you meant "shift" ;)
>

oh my god


> >    formalized introductory section.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
>
> Happy to adjust commit messages without a respin.
>

ACK, yes please ...

>

[-- Attachment #2: Type: text/html, Size: 1676 bytes --]

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

[John Snow]

[-- Attachment #1: Type: text/plain, Size: 756 bytes --]

On Tue, Sep 29, 2026, 2:17 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > Convert, or split off, intro sections for commands defined in
> > block.json and block-export.json. In general, this does not currently
>
> Suggest to scratch "In general".
>

ACK


> > impact the way these commands are rendered, except:
> >
> > 1. blockdev-open-tray and blockdev-close-tray see their opening
> >    paragraphs split apart, which is reflected in the rendered output,
> >    and
> >
> > 2. block_set_io_throttle and nbd-server-add see their argument
> >    definitions move up to just below the formalized introductory
> >    section.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
>
>

[-- Attachment #2: Type: text/html, Size: 1558 bytes --]

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

[John Snow]

[-- Attachment #1: Type: text/plain, Size: 997 bytes --]

On Tue, Sep 29, 2026, 2:22 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > Convert or split apart the existing intro for any remaining commands
> > in the QAPI schema into introduction and details sections. The
> > introduction is indented, remaining plaintext/details paragraphs
> > are not.
> >
> > For commands that have automatically generated documentation inserted
> > at parse time, these new split points serve as the new insertion
> > point. This affects the rendered documentation for `netdev_add` in
> > particular, whose arguments descriptions are pushed upwards.
>
> Missing: query-stats arguments and query-gic-capabilities "Return:" move
> up.
>

d'oh.


> >
> > Minor rephrasings are applied for `query-qmp-schema` to help
> > the split flow better in rendered documentation.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
>
> Happy to adjust commit messages without a respin.
>

Yes please.

>

[-- Attachment #2: Type: text/html, Size: 2033 bytes --]

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

[John Snow]

[-- Attachment #1: Type: text/plain, Size: 1026 bytes --]

On Tue, Sep 29, 2026, 2:24 AM Markus Armbruster <armbru@redhat.com> wrote:

> 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 left behind
> > when inlined into other contexts, but will still display the intro
> > section on standalone documentation for these types.
> >
> > In general, this patch does not change how the rendered documentation
> > currently looks, except:
>
> Suggest to scratch "In general".
>

ACK


> > 1. MemoryBackendShmProperties and MemoryBackendEpcProperties see their
> >    member descriptions move upwards to just below their formalized
> >    introductory sections.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
>
> Happy to adjust commit messages without a respin.
>

Yes, please!

>

[-- Attachment #2: Type: text/html, Size: 2058 bytes --]