[PATCH 00/12] qapi: convert simple command intro sections

[PATCH 00/12] qapi: convert simple command intro sections

[John Snow]

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

"simple" here is a non-technical distinction that means a single
paragraph of text followed by an existing section boundary that
naturally already delineates what comprises the intro.
(This is about 25% of the remaining conversions.)

If you are a non-QAPI maintainer who has been CC'd on this series,
there is likely very little for you to look at in this series. What
you need to know is that indented paragraphs become part of a
command's "intro" and will appear "above the fold" - above additional
detail in our generated QMP documentation (i.e. features, arguments,
return value, errors, etc) and anything else will eventually appear
"below the fold" - below the detail table, alongside examples, notes,
and more verbose prose.

As command definitions cannot be inlined by any other definition, the
documentation text for commands will never be re-written or reproduced
in any other context. As such, the distinction between "intro" and
"details" are less important here, but the distinction does still
determine where auto-generated documentation will be inserted, if any:
i.e. features, arguments, and return values will always be inserted
"after the intro".

John Snow (12):
  qapi: convert simple command intros for ebpf.json
  qapi: convert simple command intros for yank.json
  qapi: convert simple command intros for replay.json
  qapi: convert simple command intros for machine-s390x.json
  qapi: convert simple command intros for dump.json
  qapi: convert simple command intros for block-export.json
  qapi: convert simple command intros for block.json
  qapi: convert simple command intros for cxl.json
  qapi: convert simple command intros for ui.json
  qapi: convert simple command intros for migration.json
  qapi: convert simple command intros for machine.json
  qapi: convert simple command intros for block-core.json

 qapi/block-core.json    | 96 ++++++++++++++++++++---------------------
 qapi/block-export.json  | 18 ++++----
 qapi/block.json         |  8 ++--
 qapi/cxl.json           | 74 +++++++++++++++----------------
 qapi/dump.json          |  5 +--
 qapi/ebpf.json          |  8 ++--
 qapi/machine-s390x.json |  7 ++-
 qapi/machine.json       | 18 ++++----
 qapi/migration.json     | 51 ++++++++++------------
 qapi/replay.json        | 39 ++++++++---------
 qapi/ui.json            | 11 +++--
 qapi/yank.json          |  5 +--
 12 files changed, 157 insertions(+), 183 deletions(-)

-- 
2.55.0

[PATCH 01/12] qapi: convert simple command intros for ebpf.json

[John Snow]

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

diff --git a/qapi/ebpf.json b/qapi/ebpf.json
index 951516b121f..1f7a4d5c126 100644
--- a/qapi/ebpf.json
+++ b/qapi/ebpf.json
@@ -47,10 +47,10 @@
 
 ##
 # @request-ebpf:
-#
-# Retrieve an eBPF object that can be loaded with libbpf.  Management
-# applications (e.g. libvirt) may load it and pass file descriptors to
-# QEMU, so they can run running QEMU without BPF capabilities.
+#     Retrieve an eBPF object that can be loaded with libbpf.
+#     Management applications (e.g. libvirt) may load it and pass file
+#     descriptors to QEMU, so they can run running QEMU without BPF
+#     capabilities.
 #
 # @id: The ID of the program to return.
 #
-- 
2.55.0

[PATCH 02/12] qapi: convert simple command intros for yank.json

[John Snow]

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

diff --git a/qapi/yank.json b/qapi/yank.json
index bc8c52bda74..9a5aea82f1d 100644
--- a/qapi/yank.json
+++ b/qapi/yank.json
@@ -73,9 +73,8 @@
 
 ##
 # @yank:
-#
-# Try to recover from hanging QEMU by yanking the specified instances.
-# See `YankInstance` for more information.
+#     Try to recover from hanging QEMU by yanking the specified
+#     instances.  See `YankInstance` for more information.
 #
 # @instances: the instances to be yanked
 #
-- 
2.55.0

[PATCH 03/12] qapi: convert simple command intros for replay.json

[John Snow]

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

diff --git a/qapi/replay.json b/qapi/replay.json
index 66dff797553..db1440c09a6 100644
--- a/qapi/replay.json
+++ b/qapi/replay.json
@@ -45,10 +45,9 @@
 
 ##
 # @query-replay:
-#
-# Retrieve the record/replay information.  It includes current
-# instruction count which may be used for `replay-break` and
-# `replay-seek` commands.
+#     Retrieve the record/replay information.  It includes current
+#     instruction count which may be used for `replay-break` and
+#     `replay-seek` commands.
 #
 # Returns: record/replay information.
 #
@@ -64,13 +63,13 @@
 
 ##
 # @replay-break:
-#
-# Set replay breakpoint at instruction count @icount.  Execution stops
-# when the specified instruction is reached.  There can be at most one
-# breakpoint.  When breakpoint is set, any prior one is removed.  The
-# breakpoint may be set only in replay mode and only "in the future",
-# i.e. at instruction counts greater than the current one.  The
-# current instruction count can be observed with `query-replay`.
+#     Set replay breakpoint at instruction count @icount.  Execution
+#     stops when the specified instruction is reached.  There can be
+#     at most one breakpoint.  When breakpoint is set, any prior one
+#     is removed.  The breakpoint may be set only in replay mode and
+#     only "in the future", i.e. at instruction counts greater than
+#     the current one.  The current instruction count can be observed
+#     with `query-replay`.
 #
 # @icount: instruction count to stop at
 #
@@ -85,9 +84,8 @@
 
 ##
 # @replay-delete-break:
-#
-# Remove replay breakpoint which was set with `replay-break`.  The
-# command is ignored when there are no replay breakpoints.
+#     Remove replay breakpoint which was set with `replay-break`.  The
+#     command is ignored when there are no replay breakpoints.
 #
 # Since: 5.2
 #
@@ -100,13 +98,12 @@
 
 ##
 # @replay-seek:
-#
-# Automatically proceed to the instruction count @icount, when
-# replaying the execution.  The command automatically loads nearest
-# snapshot and replays the execution to find the desired instruction.
-# When there is no preceding snapshot or the execution is not
-# replayed, then the command fails.  Instruction count can be obtained
-# with the `query-replay` command.
+#     Automatically proceed to the instruction count @icount, when
+#     replaying the execution.  The command automatically loads
+#     nearest snapshot and replays the execution to find the desired
+#     instruction.  When there is no preceding snapshot or the
+#     execution is not replayed, then the command fails.  Instruction
+#     count can be obtained with the `query-replay` command.
 #
 # @icount: target instruction count
 #
-- 
2.55.0

[PATCH 04/12] qapi: convert simple command intros for machine-s390x.json

[John Snow]

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

diff --git a/qapi/machine-s390x.json b/qapi/machine-s390x.json
index a83a258d6ce..dcbad9b4039 100644
--- a/qapi/machine-s390x.json
+++ b/qapi/machine-s390x.json
@@ -20,10 +20,9 @@
 
 ##
 # @set-cpu-topology:
-#
-# Modify the topology by moving the CPU inside the topology tree, or
-# by changing a modifier attribute of a CPU.  Absent values will not
-# be modified.
+#     Modify the topology by moving the CPU inside the topology tree,
+#     or by changing a modifier attribute of a CPU.  Absent values
+#     will not be modified.
 #
 # @core-id: the vCPU ID to be moved
 #
-- 
2.55.0

[PATCH 05/12] qapi: convert simple command intros for dump.json

[John Snow]

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

diff --git a/qapi/dump.json b/qapi/dump.json
index 520c58cbcd8..9e97e8431f4 100644
--- a/qapi/dump.json
+++ b/qapi/dump.json
@@ -55,9 +55,8 @@
 
 ##
 # @dump-guest-memory:
-#
-# Dump guest's memory to vmcore.  It is a synchronous operation that
-# can take very long depending on the amount of guest memory.
+#     Dump guest's memory to vmcore.  It is a synchronous operation
+#     that can take very long depending on the amount of guest memory.
 #
 # @paging: if true, do paging to get guest's memory mapping.  This
 #     allows using gdb to process the core file.
-- 
2.55.0

[PATCH 06/12] qapi: convert simple command intros for block-export.json

[John Snow]

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

diff --git a/qapi/block-export.json b/qapi/block-export.json
index 154f07b0b95..2893c6456d5 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -63,11 +63,11 @@
 
 ##
 # @nbd-server-start:
-#
-# Start an NBD server listening on the given host and port.  Block
-# devices can then be exported using `nbd-server-add`.  The NBD server
-# will present them as named exports; for example, another QEMU
-# instance could refer to them as "nbd:HOST:PORT:exportname=NAME".
+#     Start an NBD server listening on the given host and port.  Block
+#     devices can then be exported using `nbd-server-add`.  The NBD
+#     server will present them as named exports; for example, another
+#     QEMU instance could refer to them as
+#     "nbd:HOST:PORT:exportname=NAME".
 #
 # Errors:
 #     - if the server is already running
@@ -435,10 +435,10 @@
 
 ##
 # @block-export-del:
-#
-# Request to remove a block export.  This drops the user's reference
-# to the export, but the export may still stay around after this
-# command returns until the shutdown of the export has completed.
+#     Request to remove a block export.  This drops the user's
+#     reference to the export, but the export may still stay around
+#     after this command returns until the shutdown of the export has
+#     completed.
 #
 # @id: Block export id.
 #
-- 
2.55.0

[PATCH 07/12] qapi: convert simple command intros for block.json

[John Snow]

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

diff --git a/qapi/block.json b/qapi/block.json
index 189f2e28204..9569afc6e0f 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -261,10 +261,10 @@
 
 ##
 # @blockdev-insert-medium:
-#
-# Inserts a medium (a block driver state tree) into a block device.
-# That block device's tray must currently be open (unless there is no
-# attached guest device) and there must be no medium inserted already.
+#     Inserts a medium (a block driver state tree) into a block
+#     device.  That block device's tray must currently be open (unless
+#     there is no attached guest device) and there must be no medium
+#     inserted already.
 #
 # @id: The name or QOM path of the guest device
 #
-- 
2.55.0

[PATCH 08/12] qapi: convert simple command intros for cxl.json

[John Snow]

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

diff --git a/qapi/cxl.json b/qapi/cxl.json
index aef849a4c2a..58ad82c2dc7 100644
--- a/qapi/cxl.json
+++ b/qapi/cxl.json
@@ -118,10 +118,9 @@
 
 ##
 # @cxl-inject-general-media-event:
-#
-# Inject an event record for a General Media Event (CXL r3.2
-# 8.2.10.2.1.1).  This event type is reported via one of the event
-# logs specified via the log parameter.
+#     Inject an event record for a General Media Event (CXL r3.2
+#     8.2.10.2.1.1).  This event type is reported via one of the event
+#     logs specified via the log parameter.
 #
 # Since: 8.1
 ##
@@ -201,10 +200,9 @@
 
 ##
 # @cxl-inject-dram-event:
-#
-# Inject an event record for a DRAM Event (CXL r3.2 8.2.10.2.1.2).
-# This event type is reported via one of the event logs
-# specified via the log parameter.
+#     Inject an event record for a DRAM Event (CXL r3.2 8.2.10.2.1.2).
+#     This event type is reported via one of the event logs specified
+#     via the log parameter.
 #
 # Since: 8.1
 ##
@@ -267,10 +265,9 @@
 
 ##
 # @cxl-inject-memory-module-event:
-#
-# Inject an event record for a Memory Module Event (CXL r3.2
-# 8.2.10.2.1.3).  This event includes a copy of the Device Health info
-# at the time of the event.
+#     Inject an event record for a Memory Module Event (CXL r3.2
+#     8.2.10.2.1.3).  This event includes a copy of the Device Health
+#     info at the time of the event.
 #
 # Since: 8.1
 ##
@@ -279,13 +276,12 @@
 
 ##
 # @cxl-inject-poison:
-#
-# Poison records indicate that a CXL memory device knows that a
-# particular memory region may be corrupted.  This may be because of
-# locally detected errors (e.g. ECC failure) or poisoned writes
-# received from other components in the system.  This injection
-# mechanism enables testing of the OS handling of poison records which
-# may be queried via the CXL mailbox.
+#     Poison records indicate that a CXL memory device knows that a
+#     particular memory region may be corrupted.  This may be because
+#     of locally detected errors (e.g. ECC failure) or poisoned writes
+#     received from other components in the system.  This injection
+#     mechanism enables testing of the OS handling of poison records
+#     which may be queried via the CXL mailbox.
 #
 # @path: CXL type 3 device canonical QOM path
 #
@@ -382,9 +378,8 @@
 
 ##
 # @cxl-inject-uncorrectable-errors:
-#
-# Command to allow injection of multiple errors in one go.  This
-# allows testing of multiple header log handling in the OS.
+#     Command to allow injection of multiple errors in one go.  This
+#     allows testing of multiple header log handling in the OS.
 #
 # @path: CXL Type 3 device canonical QOM path
 #
@@ -430,12 +425,11 @@
 
 ##
 # @cxl-inject-correctable-error:
-#
-# Command to inject a single correctable error.  Multiple error
-# injection of this error type is not interesting as there is no
-# associated header log.  These errors are reported via AER as a
-# correctable internal error, with additional detail available from
-# the CXL device.
+#     Command to inject a single correctable error.  Multiple error
+#     injection of this error type is not interesting as there is no
+#     associated header log.  These errors are reported via AER as a
+#     correctable internal error, with additional detail available
+#     from the CXL device.
 #
 # @path: CXL Type 3 device canonical QOM path
 #
@@ -510,12 +504,12 @@
 
 ##
 # @cxl-add-dynamic-capacity:
-#
-# Initiate adding dynamic capacity extents to a host.  This simulates
-# operations defined in Compute Express Link (CXL) Specification,
-# Revision 3.1, Section 7.6.7.6.5.  Note that, currently, establishing
-# success or failure of the full Add Dynamic Capacity flow requires
-# out of band communication with the OS of the CXL host.
+#     Initiate adding dynamic capacity extents to a host.  This
+#     simulates operations defined in Compute Express Link (CXL)
+#     Specification, Revision 3.1, Section 7.6.7.6.5.  Note that,
+#     currently, establishing success or failure of the full Add
+#     Dynamic Capacity flow requires out of band communication with
+#     the OS of the CXL host.
 #
 # @path: path to the CXL Dynamic Capacity Device in the QOM tree.
 #
@@ -576,12 +570,12 @@
 
 ##
 # @cxl-release-dynamic-capacity:
-#
-# Initiate release of dynamic capacity extents from a host.  This
-# simulates operations defined in Compute Express Link (CXL)
-# Specification, Revision 3.1, Section 7.6.7.6.6.  Note that,
-# currently, success or failure of the full Release Dynamic Capacity
-# flow requires out of band communication with the OS of the CXL host.
+#     Initiate release of dynamic capacity extents from a host.  This
+#     simulates operations defined in Compute Express Link (CXL)
+#     Specification, Revision 3.1, Section 7.6.7.6.6.  Note that,
+#     currently, success or failure of the full Release Dynamic
+#     Capacity flow requires out of band communication with the OS of
+#     the CXL host.
 #
 # @path: path to the CXL Dynamic Capacity Device in the QOM tree.
 #
-- 
2.55.0

[PATCH 09/12] qapi: convert simple command intros for ui.json

[John Snow]

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

diff --git a/qapi/ui.json b/qapi/ui.json
index 960d02d1429..a59cd635774 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -656,8 +656,7 @@
 
 ##
 # @query-vnc-servers:
-#
-# Return a list of vnc servers.  The list can be empty.
+#     Return a list of vnc servers.  The list can be empty.
 #
 # Since: 2.3
 ##
@@ -1634,10 +1633,10 @@
 
 ##
 # @client_migrate_info:
-#
-# Set migration information for remote display.  This makes the server
-# ask the client to automatically reconnect using the new parameters
-# once migration finished successfully.  Only implemented for SPICE.
+#     Set migration information for remote display.  This makes the
+#     server ask the client to automatically reconnect using the new
+#     parameters once migration finished successfully.  Only
+#     implemented for SPICE.
 #
 # @protocol: must be "spice"
 #
-- 
2.55.0

[PATCH 10/12] qapi: convert simple command intros for migration.json

[John Snow]

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

diff --git a/qapi/migration.json b/qapi/migration.json
index 8b6abcee2ca..e3beaea87bb 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -333,9 +333,9 @@
 
 ##
 # @query-migrate:
-#
-# Return information about current migration process.  If migration is
-# active there will be another json-object with RAM migration status.
+#     Return information about current migration process.  If
+#     migration is active there will be another json-object with RAM
+#     migration status.
 #
 # Since: 0.14
 #
@@ -824,8 +824,7 @@
 
 ##
 # @migrate-set-parameters:
-#
-# Set migration parameters.  All arguments are optional.
+#     Set migration parameters.  All arguments are optional.
 #
 # Since: 2.4
 #
@@ -1047,11 +1046,10 @@
 
 ##
 # @query-migrate-parameters:
-#
-# Return information about the current migration parameters.  Optional
-# members of the return value are always present, except
-# @block-bitmap-mapping, which is only present if it has been
-# previously set.
+#     Return information about the current migration parameters.
+#     Optional members of the return value are always present, except
+#     @block-bitmap-mapping, which is only present if it has been
+#     previously set.
 #
 # Since: 2.4
 #
@@ -1072,10 +1070,9 @@
 
 ##
 # @migrate-start-postcopy:
-#
-# Followup to a migration command to switch the migration to postcopy
-# mode.  The postcopy-ram capability must be set on both source and
-# destination before the original migration command.
+#     Followup to a migration command to switch the migration to
+#     postcopy mode.  The postcopy-ram capability must be set on both
+#     source and destination before the original migration command.
 #
 # Since: 2.5
 #
@@ -1222,12 +1219,11 @@
 
 ##
 # @x-colo-lost-heartbeat:
-#
-# Tell QEMU that heartbeat is lost, request it to do takeover
-# procedures.  If this command is sent to the PVM, the Primary side
-# will exit COLO mode.  If sent to the Secondary, the Secondary side
-# will run failover work, then takes over server operation to become
-# the service VM.
+#     Tell QEMU that heartbeat is lost, request it to do takeover
+#     procedures.  If this command is sent to the PVM, the Primary
+#     side will exit COLO mode.  If sent to the Secondary, the
+#     Secondary side will run failover work, then takes over server
+#     operation to become the service VM.
 #
 # Features:
 #
@@ -1442,9 +1438,8 @@
 
 ##
 # @migrate-incoming:
-#
-# Start an incoming migration.  QEMU must have been started with
-# -incoming defer.
+#     Start an incoming migration.  QEMU must have been started with
+#     -incoming defer.
 #
 # @uri: The Uniform Resource Identifier identifying the source or
 #     address to listen on
@@ -1514,9 +1509,8 @@
 
 ##
 # @xen-save-devices-state:
-#
-# Save the state of all devices to file.  The RAM and the block
-# devices of the VM are not saved by this command.
+#     Save the state of all devices to file.  The RAM and the block
+#     devices of the VM are not saved by this command.
 #
 # @filename: the file to save the state of the devices to as binary
 #     data.  See `xen-save-devices-state`.txt for a description of the
@@ -1554,9 +1548,8 @@
 
 ##
 # @xen-load-devices-state:
-#
-# Load the state of all devices from file.  The RAM and the block
-# devices of the VM are not loaded by this command.
+#     Load the state of all devices from file.  The RAM and the block
+#     devices of the VM are not loaded by this command.
 #
 # @filename: the file to load the state of the devices from as binary
 #     data.  See `xen-save-devices-state`.txt for a description of the
-- 
2.55.0

[PATCH 11/12] qapi: convert simple command intros for machine.json

[John Snow]

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

diff --git a/qapi/machine.json b/qapi/machine.json
index 8ef12504d65..9d709cb53e0 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -363,11 +363,10 @@
 
 ##
 # @system_wakeup:
-#
-# Wake up guest from suspend.  If the guest has wake-up from suspend
-# support enabled (wakeup-suspend-support flag from
-# `query-current-machine`), wake-up guest from suspend if the guest is
-# in SUSPENDED state.  Return an error otherwise.
+#     Wake up guest from suspend.  If the guest has wake-up from
+#     suspend support enabled (wakeup-suspend-support flag from
+#     `query-current-machine`), wake-up guest from suspend if the
+#     guest is in SUSPENDED state.  Return an error otherwise.
 #
 # Since: 1.1
 #
@@ -415,11 +414,10 @@
 
 ##
 # @inject-nmi:
-#
-# Injects a Non-Maskable Interrupt (machine specific: for example on
-# s390x CCW only the first vCPU receives the NMI, but on x86 machines
-# all vCPUs receive it).  The command fails when the guest doesn't
-# support injecting.
+#     Injects a Non-Maskable Interrupt (machine specific: for example
+#     on s390x CCW only the first vCPU receives the NMI, but on x86
+#     machines all vCPUs receive it).  The command fails when the
+#     guest doesn't support injecting.
 #
 # Since: 0.14
 #
-- 
2.55.0

[PATCH 12/12] qapi: convert simple command intros for block-core.json

[John Snow]

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

diff --git a/qapi/block-core.json b/qapi/block-core.json
index 33e1147792b..29f011dc209 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1816,12 +1816,12 @@
 
 ##
 # @change-backing-file:
-#
-# Change the backing file in the image file metadata.  This does not
-# cause QEMU to reopen the image file to reparse the backing filename
-# (it may, however, perform a reopen to change permissions from r/o ->
-# r/w -> r/o, if needed).  The new backing file string is written into
-# the image file metadata, and the QEMU internal strings are updated.
+#     Change the backing file in the image file metadata.  This does
+#     not cause QEMU to reopen the image file to reparse the backing
+#     filename (it may, however, perform a reopen to change
+#     permissions from r/o -> r/w -> r/o, if needed).  The new backing
+#     file string is written into the image file metadata, and the
+#     QEMU internal strings are updated.
 #
 # @image-node-name: The name of the block driver state node of the
 #     image to modify.  The "device" argument is used to verify
@@ -1957,12 +1957,12 @@
 
 ##
 # @drive-backup:
-#
-# Start a point-in-time copy of a block device to a new destination.
-# The status of ongoing `drive-backup` operations can be checked with
-# `query-block-jobs` where the `BlockJobInfo`.type field has the value
-# 'backup'.  The operation can be stopped before it has completed
-# using the `job-cancel` or `block-job-cancel` command.
+#     Start a point-in-time copy of a block device to a new
+#     destination.  The status of ongoing `drive-backup` operations
+#     can be checked with `query-block-jobs` where the
+#     `BlockJobInfo`.type field has the value 'backup'.  The operation
+#     can be stopped before it has completed using the `job-cancel` or
+#     `block-job-cancel` command.
 #
 # Features:
 #
@@ -1988,12 +1988,12 @@
 
 ##
 # @blockdev-backup:
-#
-# Start a point-in-time copy of a block device to a new destination.
-# The status of ongoing `blockdev-backup` operations can be checked
-# with `query-block-jobs` where the `BlockJobInfo`.type field has the
-# value 'backup'.  The operation can be stopped before it has
-# completed using the `job-cancel` or `block-job-cancel` command.
+#     Start a point-in-time copy of a block device to a new
+#     destination.  The status of ongoing `blockdev-backup` operations
+#     can be checked with `query-block-jobs` where the
+#     `BlockJobInfo`.type field has the value 'backup'.  The operation
+#     can be stopped before it has completed using the `job-cancel` or
+#     `block-job-cancel` command.
 #
 # Errors:
 #     - If @device is not a valid block device, DeviceNotFound
@@ -2185,13 +2185,13 @@
 
 ##
 # @drive-mirror:
-#
-# Start mirroring a block device's writes to a new destination.
-# target specifies the target of the new image.  If the file exists,
-# or if it is a device, it will be used as the new destination for
-# writes.  If it does not exist, a new file will be created.  @format
-# specifies the format of the mirror image, default is to probe if
-# mode='existing', else the format of the source.
+#     Start mirroring a block device's writes to a new destination.
+#     target specifies the target of the new image.  If the file
+#     exists, or if it is a device, it will be used as the new
+#     destination for writes.  If it does not exist, a new file will
+#     be created.  @format specifies the format of the mirror image,
+#     default is to probe if mode='existing', else the format of the
+#     source.
 #
 # Errors:
 #     - If @device is not a valid block device, GenericError
@@ -2387,10 +2387,9 @@
 
 ##
 # @block-dirty-bitmap-remove:
-#
-# Stop write tracking and remove the dirty bitmap that was created
-# with `block-dirty-bitmap-add`.  If the bitmap is persistent, remove
-# it from its storage too.
+#     Stop write tracking and remove the dirty bitmap that was created
+#     with `block-dirty-bitmap-add`.  If the bitmap is persistent,
+#     remove it from its storage too.
 #
 # Errors:
 #     - If @node is not a valid block device or node, DeviceNotFound
@@ -4937,10 +4936,9 @@
 
 ##
 # @blockdev-del:
-#
-# Deletes a block device that has been added using `blockdev-add`.
-# The command will fail if the node is attached to a device or is
-# otherwise being used.
+#     Deletes a block device that has been added using `blockdev-add`.
+#     The command will fail if the node is attached to a device or is
+#     otherwise being used.
 #
 # @node-name: Name of the graph node to delete.
 #
@@ -5453,9 +5451,9 @@
 
 ##
 # @blockdev-create:
-#
-# Starts a job to create an image format on a given node.  The job is
-# automatically finalized, but a manual `job-dismiss` is required.
+#     Starts a job to create an image format on a given node.  The job
+#     is automatically finalized, but a manual `job-dismiss` is
+#     required.
 #
 # @job-id: Identifier for the newly created job.
 #
@@ -5510,10 +5508,9 @@
 
 ##
 # @x-blockdev-amend:
-#
-# Starts a job to amend format specific options of an existing open
-# block device.  The job is automatically finalized, but a manual
-# `job-dismiss` is required.
+#     Starts a job to amend format specific options of an existing
+#     open block device.  The job is automatically finalized, but a
+#     manual `job-dismiss` is required.
 #
 # @job-id: Identifier for the newly created job.
 #
@@ -6087,11 +6084,10 @@
 
 ##
 # @blockdev-snapshot-internal-sync:
-#
-# Synchronously take an internal snapshot of a block device, when the
-# format of the image used supports it.  If the name is an empty
-# string, or a snapshot with name already exists, the operation will
-# fail.
+#     Synchronously take an internal snapshot of a block device, when
+#     the format of the image used supports it.  If the name is an
+#     empty string, or a snapshot with name already exists, the
+#     operation will fail.
 #
 # Errors:
 #     - If @device is not a valid block device, GenericError
@@ -6119,11 +6115,11 @@
 
 ##
 # @blockdev-snapshot-delete-internal-sync:
-#
-# Synchronously delete an internal snapshot of a block device, when
-# the format of the image used support it.  The snapshot is identified
-# by name or id or both.  One of the name or id is required.  Return
-# `SnapshotInfo` for the successfully deleted snapshot.
+#     Synchronously delete an internal snapshot of a block device,
+#     when the format of the image used support it.  The snapshot is
+#     identified by name or id or both.  One of the name or id is
+#     required.  Return `SnapshotInfo` for the successfully deleted
+#     snapshot.
 #
 # @device: the device name or node-name of a root node to delete the
 #     snapshot from
-- 
2.55.0

Re: [PATCH 12/12] qapi: convert simple command intros for block-core.json

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/block-core.json | 96 +++++++++++++++++++++-----------------------
>  1 file changed, 46 insertions(+), 50 deletions(-)
>
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index 33e1147792b..29f011dc209 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -1816,12 +1816,12 @@
>  
>  ##
>  # @change-backing-file:
> -#
> -# Change the backing file in the image file metadata.  This does not
> -# cause QEMU to reopen the image file to reparse the backing filename
> -# (it may, however, perform a reopen to change permissions from r/o ->
> -# r/w -> r/o, if needed).  The new backing file string is written into
> -# the image file metadata, and the QEMU internal strings are updated.
> +#     Change the backing file in the image file metadata.  This does
> +#     not cause QEMU to reopen the image file to reparse the backing
> +#     filename (it may, however, perform a reopen to change
> +#     permissions from r/o -> r/w -> r/o, if needed).  The new backing
> +#     file string is written into the image file metadata, and the
> +#     QEMU internal strings are updated.
>  #
>  # @image-node-name: The name of the block driver state node of the
>  #     image to modify.  The "device" argument is used to verify
> @@ -1957,12 +1957,12 @@
>  
>  ##
>  # @drive-backup:
> -#
> -# Start a point-in-time copy of a block device to a new destination.
> -# The status of ongoing `drive-backup` operations can be checked with
> -# `query-block-jobs` where the `BlockJobInfo`.type field has the value
> -# 'backup'.  The operation can be stopped before it has completed
> -# using the `job-cancel` or `block-job-cancel` command.
> +#     Start a point-in-time copy of a block device to a new
> +#     destination.  The status of ongoing `drive-backup` operations
> +#     can be checked with `query-block-jobs` where the
> +#     `BlockJobInfo`.type field has the value 'backup'.  The operation
> +#     can be stopped before it has completed using the `job-cancel` or
> +#     `block-job-cancel` command.
>  #
>  # Features:
>  #
> @@ -1988,12 +1988,12 @@
>  
>  ##
>  # @blockdev-backup:
> -#
> -# Start a point-in-time copy of a block device to a new destination.
> -# The status of ongoing `blockdev-backup` operations can be checked
> -# with `query-block-jobs` where the `BlockJobInfo`.type field has the
> -# value 'backup'.  The operation can be stopped before it has
> -# completed using the `job-cancel` or `block-job-cancel` command.
> +#     Start a point-in-time copy of a block device to a new
> +#     destination.  The status of ongoing `blockdev-backup` operations
> +#     can be checked with `query-block-jobs` where the
> +#     `BlockJobInfo`.type field has the value 'backup'.  The operation
> +#     can be stopped before it has completed using the `job-cancel` or
> +#     `block-job-cancel` command.
>  #
>  # Errors:
>  #     - If @device is not a valid block device, DeviceNotFound
> @@ -2185,13 +2185,13 @@
>  
>  ##
>  # @drive-mirror:
> -#
> -# Start mirroring a block device's writes to a new destination.
> -# target specifies the target of the new image.  If the file exists,
> -# or if it is a device, it will be used as the new destination for
> -# writes.  If it does not exist, a new file will be created.  @format
> -# specifies the format of the mirror image, default is to probe if
> -# mode='existing', else the format of the source.
> +#     Start mirroring a block device's writes to a new destination.
> +#     target specifies the target of the new image.  If the file

@target, I think.

> +#     exists, or if it is a device, it will be used as the new
> +#     destination for writes.  If it does not exist, a new file will
> +#     be created.  @format specifies the format of the mirror image,
> +#     default is to probe if mode='existing', else the format of the

@mode

Where there are two, there are almost certainly more.

> +#     source.

Text that refers to arguments should probably go below the argument
descriptions.  I.e. this "intro" should probably be split.

Let's leave that for another day, just take note of future work:

1. Add missing markup to argument / member / feature references.

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

Not noting any of this again for this series.

>  #
>  # Errors:
>  #     - If @device is not a valid block device, GenericError
> @@ -2387,10 +2387,9 @@
>  
>  ##
>  # @block-dirty-bitmap-remove:
> -#
> -# Stop write tracking and remove the dirty bitmap that was created
> -# with `block-dirty-bitmap-add`.  If the bitmap is persistent, remove
> -# it from its storage too.
> +#     Stop write tracking and remove the dirty bitmap that was created
> +#     with `block-dirty-bitmap-add`.  If the bitmap is persistent,
> +#     remove it from its storage too.
>  #
>  # Errors:
>  #     - If @node is not a valid block device or node, DeviceNotFound
> @@ -4937,10 +4936,9 @@
>  
>  ##
>  # @blockdev-del:
> -#
> -# Deletes a block device that has been added using `blockdev-add`.
> -# The command will fail if the node is attached to a device or is
> -# otherwise being used.
> +#     Deletes a block device that has been added using `blockdev-add`.
> +#     The command will fail if the node is attached to a device or is
> +#     otherwise being used.

Perhaps the "will fail" part should be in an Errors: section.

The intros above use imperative mode, this one doesn't.  Elsewhere in
this series, I even saw "Command to <do stuff>".

More notes:

3. Review and improve doc comments where the intro talks about failure
modes.

4. Consistently use imperative mood for command intros.

Not noting any of this again for this series.

>  #
>  # @node-name: Name of the graph node to delete.
>  #

[...]

Re: [PATCH 00/12] qapi: convert simple command intro sections

[Markus Armbruster]

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

Re: [PATCH 00/12] qapi: convert simple command intro sections

[John Snow]

On Thu, Sep 3, 2026 at 8:00 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> Series
> Reviewed-by: Markus Armbruster <armbru@redhat.com>
>

Nice!