* [PATCH 01/13] qapi: Tidy up run-together sentences in doc comments
2025-05-27 7:39 [PATCH 00/13] qapi: Doc fixes and improvements Markus Armbruster
@ 2025-05-27 7:39 ` Markus Armbruster
2025-05-27 7:39 ` [PATCH 02/13] qapi: Tidy up whitespace " Markus Armbruster
` (13 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Markus Armbruster @ 2025-05-27 7:39 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, kwolf, jsnow, vsementsov, qemu-block
Fixes: a937b6aa739f (qapi: Reformat doc comments to conform to current conventions)
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/acpi.json | 2 +-
qapi/block-core.json | 14 +++++++-------
qapi/crypto.json | 18 +++++++++---------
qapi/machine.json | 4 ++--
qapi/migration.json | 18 +++++++++---------
5 files changed, 28 insertions(+), 28 deletions(-)
diff --git a/qapi/acpi.json b/qapi/acpi.json
index 045dab6228..2d53b82365 100644
--- a/qapi/acpi.json
+++ b/qapi/acpi.json
@@ -80,7 +80,7 @@
##
# @ACPIOSTInfo:
#
-# OSPM Status Indication for a device For description of possible
+# OSPM Status Indication for a device. For description of possible
# values of @source and @status fields see "_OST (OSPM Status
# Indication)" chapter of ACPI5.0 spec.
#
diff --git a/qapi/block-core.json b/qapi/block-core.json
index b4115113d4..29d7c1c2c9 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -2667,7 +2667,7 @@
# @iops-total-max: I/O operations burst
#
# @iops-total-max-length: length of the iops-total-max burst period,
-# in seconds It must only be set if @iops-total-max is set as
+# in seconds. It must only be set if @iops-total-max is set as
# well.
#
# @iops-read: limit read operations per second
@@ -2675,14 +2675,14 @@
# @iops-read-max: I/O operations read burst
#
# @iops-read-max-length: length of the iops-read-max burst period, in
-# seconds It must only be set if @iops-read-max is set as well.
+# seconds. It must only be set if @iops-read-max is set as well.
#
# @iops-write: limit write operations per second
#
# @iops-write-max: I/O operations write burst
#
# @iops-write-max-length: length of the iops-write-max burst period,
-# in seconds It must only be set if @iops-write-max is set as
+# in seconds. It must only be set if @iops-write-max is set as
# well.
#
# @bps-total: limit total bytes per second
@@ -2697,14 +2697,14 @@
# @bps-read-max: total bytes read burst
#
# @bps-read-max-length: length of the bps-read-max burst period, in
-# seconds It must only be set if @bps-read-max is set as well.
+# seconds. It must only be set if @bps-read-max is set as well.
#
# @bps-write: limit write bytes per second
#
# @bps-write-max: total bytes write burst
#
# @bps-write-max-length: length of the bps-write-max burst period, in
-# seconds It must only be set if @bps-write-max is set as well.
+# seconds. It must only be set if @bps-write-max is set as well.
#
# @iops-size: when limiting by iops max size of an I/O in bytes
#
@@ -5580,7 +5580,7 @@
# @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
+# block device. The job is automatically finalized, but a manual
# job-dismiss is required.
#
# @job-id: Identifier for the newly created job.
@@ -5589,7 +5589,7 @@
#
# @options: Options (driver specific)
#
-# @force: Allow unsafe operations, format specific For luks that
+# @force: Allow unsafe operations, format specific. For luks that
# allows erase of the last active keyslot (permanent loss of
# data), and replacement of an active keyslot (possible loss of
# data if IO error happens)
diff --git a/qapi/crypto.json b/qapi/crypto.json
index c9d967d782..fc7e294966 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -202,19 +202,19 @@
#
# The options that apply to LUKS encryption format initialization
#
-# @cipher-alg: the cipher algorithm for data encryption Currently
+# @cipher-alg: the cipher algorithm for data encryption. Currently
# defaults to 'aes-256'.
#
-# @cipher-mode: the cipher mode for data encryption Currently defaults
-# to 'xts'
+# @cipher-mode: the cipher mode for data encryption. Currently
+# defaults to 'xts'
#
-# @ivgen-alg: the initialization vector generator Currently defaults
+# @ivgen-alg: the initialization vector generator. Currently defaults
# to 'plain64'
#
-# @ivgen-hash-alg: the initialization vector generator hash Currently
-# defaults to 'sha256'
+# @ivgen-hash-alg: the initialization vector generator hash.
+# Currently defaults to 'sha256'
#
-# @hash-alg: the master key hash algorithm Currently defaults to
+# @hash-alg: the master key hash algorithm. Currently defaults to
# 'sha256'
#
# @iter-time: number of milliseconds to spend in PBKDF passphrase
@@ -370,11 +370,11 @@
# @new-secret: The ID of a QCryptoSecret object providing the password
# to be written into added active keyslots
#
-# @old-secret: Optional (for deactivation only) If given will
+# @old-secret: Optional (for deactivation only). If given will
# deactivate all keyslots that match password located in
# QCryptoSecret with this ID
#
-# @iter-time: Optional (for activation only) Number of milliseconds to
+# @iter-time: Optional (for activation only). Number of milliseconds to
# spend in PBKDF passphrase processing for the newly activated
# keyslot. Currently defaults to 2000.
#
diff --git a/qapi/machine.json b/qapi/machine.json
index c8feb9fe17..0c5c85d014 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1160,7 +1160,7 @@
#
# Information about the guest balloon device.
#
-# @actual: the logical size of the VM in bytes Formula used:
+# @actual: the logical size of the VM in bytes. Formula used:
# logical_vm_size = vm_ram_size - balloon_size
#
# Since: 0.14
@@ -1199,7 +1199,7 @@
# is equivalent to the @actual field return by the 'query-balloon'
# command
#
-# @actual: the logical size of the VM in bytes Formula used:
+# @actual: the logical size of the VM in bytes. Formula used:
# logical_vm_size = vm_ram_size - balloon_size
#
# .. note:: This event is rate-limited.
diff --git a/qapi/migration.json b/qapi/migration.json
index 8b9c53595c..beebc2a6f8 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -760,9 +760,9 @@
# auto-converge detects that migration is not making progress.
# The default value is 10. (Since 2.7)
#
-# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At
-# the tail stage of throttling, the Guest is very sensitive to CPU
-# percentage while the @cpu-throttle -increment is excessive
+# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage.
+# At the tail stage of throttling, the Guest is very sensitive to
+# CPU percentage while the @cpu-throttle -increment is excessive
# usually at tail stage. If this parameter is true, we will
# compute the ideal CPU percentage used by the Guest, which may
# exactly make the dirty rate match the dirty rate threshold.
@@ -941,9 +941,9 @@
# auto-converge detects that migration is not making progress.
# The default value is 10. (Since 2.7)
#
-# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At
-# the tail stage of throttling, the Guest is very sensitive to CPU
-# percentage while the @cpu-throttle -increment is excessive
+# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage.
+# At the tail stage of throttling, the Guest is very sensitive to
+# CPU percentage while the @cpu-throttle -increment is excessive
# usually at tail stage. If this parameter is true, we will
# compute the ideal CPU percentage used by the Guest, which may
# exactly make the dirty rate match the dirty rate threshold.
@@ -1155,9 +1155,9 @@
# auto-converge detects that migration is not making progress.
# (Since 2.7)
#
-# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage At
-# the tail stage of throttling, the Guest is very sensitive to CPU
-# percentage while the @cpu-throttle -increment is excessive
+# @cpu-throttle-tailslow: Make CPU throttling slower at tail stage.
+# At the tail stage of throttling, the Guest is very sensitive to
+# CPU percentage while the @cpu-throttle -increment is excessive
# usually at tail stage. If this parameter is true, we will
# compute the ideal CPU percentage used by the Guest, which may
# exactly make the dirty rate match the dirty rate threshold.
--
2.48.1
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 02/13] qapi: Tidy up whitespace in doc comments
2025-05-27 7:39 [PATCH 00/13] qapi: Doc fixes and improvements Markus Armbruster
2025-05-27 7:39 ` [PATCH 01/13] qapi: Tidy up run-together sentences in doc comments Markus Armbruster
@ 2025-05-27 7:39 ` Markus Armbruster
2025-05-27 7:39 ` [PATCH 03/13] qapi: Move (since X.Y) to end of description Markus Armbruster
` (12 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Markus Armbruster @ 2025-05-27 7:39 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, kwolf, jsnow, vsementsov, qemu-block
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/block-core.json | 16 ++++++++--------
qapi/block-export.json | 4 ++--
qapi/char.json | 2 +-
qapi/crypto.json | 3 ++-
qapi/job.json | 8 ++++----
qapi/machine.json | 2 +-
qapi/migration.json | 12 ++++++------
qapi/qom.json | 2 +-
8 files changed, 25 insertions(+), 24 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 29d7c1c2c9..13223df9b4 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -488,7 +488,7 @@
#
# @active: true if the backend is active; typical cases for inactive backends
# are on the migration source instance after migration completes and on the
-# destination before it completes. (since: 10.0)
+# destination before it completes. (since: 10.0)
#
# @encrypted: true if the backing device is encrypted
#
@@ -3030,10 +3030,10 @@
# 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
+# the device to write to the target path only. Note that drive
# mirroring includes drive-mirror, blockdev-mirror and block-commit
# job (only in case of "active commit", when the node being commited
-# is used by the guest). The ability to complete is signaled with a
+# is used by the guest). The ability to complete is signaled with a
# BLOCK_JOB_READY event.
#
# This command completes an active background block operation
@@ -3068,10 +3068,10 @@
#
# 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
+# 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
+# block-stream. @auto-dismiss is enabled by default for these
# jobs.
#
# This command will refuse to operate on any job that has not yet
@@ -4737,7 +4737,7 @@
# @active: whether the block node should be activated (default: true).
# Having inactive block nodes is useful primarily for migration because it
# allows opening an image on the destination while the source is still
-# holding locks for it. (Since 10.0)
+# holding locks for it. (Since 10.0)
#
# @read-only: whether the block device should be read-only (default:
# false). Note that some block drivers support only read-only
@@ -4999,14 +4999,14 @@
##
# @blockdev-set-active:
#
-# Activate or inactivate a block device. Use this to manage the handover of
+# Activate or inactivate 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.
# Inactivating a node automatically inactivates any of its child nodes that are
# not in use by a still active node.
#
-# @node-name: Name of the graph node to activate or inactivate. By default, all
+# @node-name: Name of the graph node to activate or inactivate. By default, all
# nodes are affected by the operation.
#
# @active: true if the nodes should be active when the command returns success,
diff --git a/qapi/block-export.json b/qapi/block-export.json
index c783e01a53..04190b503c 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -373,9 +373,9 @@
# (since: 5.2)
#
# @allow-inactive: If true, the export allows the exported node to be inactive.
-# If it is created for an inactive block node, the node remains inactive. If
+# If it is created for an inactive block node, the node remains inactive. If
# the export type doesn't support running on an inactive node, an error is
-# returned. If false, inactive block nodes are automatically activated before
+# returned. If false, inactive block nodes are automatically activated before
# creating the export and trying to inactivate them later fails.
# (since: 10.0; default: false)
#
diff --git a/qapi/char.json b/qapi/char.json
index dde2f9538f..9ad9d11cf6 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -274,7 +274,7 @@
# @reconnect: For a client socket, if a socket is disconnected, then
# attempt a reconnect after the given number of seconds. Setting
# this to zero disables this function. The use of this member is
-# deprecated, use @reconnect-ms instead. (default: 0) (Since: 2.2)
+# deprecated, use @reconnect-ms instead. (default: 0) (Since: 2.2)
#
# @reconnect-ms: For a client socket, if a socket is disconnected,
# then attempt a reconnect after the given number of milliseconds.
diff --git a/qapi/crypto.json b/qapi/crypto.json
index fc7e294966..9ec6301e18 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -55,7 +55,8 @@
# @sha512: SHA-512. (since 2.7)
#
# @ripemd160: RIPEMD-160. (since 2.7)
-# @sm3: SM3. (since 9.2.0)
+#
+# @sm3: SM3. (since 9.2.0)
#
# Since: 2.6
##
diff --git a/qapi/job.json b/qapi/job.json
index b03f80bc84..c53c96cce8 100644
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -191,10 +191,10 @@
# 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
+# the device to write to the target path only. Note that drive
# mirroring includes drive-mirror, blockdev-mirror and block-commit
# job (only in case of "active commit", when the node being commited
-# is used by the guest). The ability to complete is signaled with a
+# is used by the guest). The ability to complete is signaled with a
# BLOCK_JOB_READY event.
#
# This command completes an active background block operation
@@ -216,10 +216,10 @@
#
# 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
+# 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
+# block-stream. @auto-dismiss is enabled by default for these
# jobs.
#
# This command will refuse to operate on any job that has not yet
diff --git a/qapi/machine.json b/qapi/machine.json
index 0c5c85d014..1d60693b65 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -694,7 +694,7 @@
# 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.
+# Table 5-146: Field "Data Type" of ACPI 6.3 spec.
#
# @access-latency: access latency (nanoseconds)
#
diff --git a/qapi/migration.json b/qapi/migration.json
index beebc2a6f8..83afe17cec 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -842,9 +842,9 @@
# more CPU. Defaults to 1. (Since 5.0)
#
# @multifd-qatzip-level: Set the compression level to be used in live
-# migration. The level is an integer between 1 and 9, where 1 means
+# migration. The level is an integer between 1 and 9, where 1 means
# the best compression speed, and 9 means the best compression
-# ratio which will consume more CPU. Defaults to 1. (Since 9.2)
+# ratio which will consume more CPU. Defaults to 1. (Since 9.2)
#
# @multifd-zstd-level: Set the compression level to be used in live
# migration, the compression level is an integer between 0 and 20,
@@ -1023,9 +1023,9 @@
# more CPU. Defaults to 1. (Since 5.0)
#
# @multifd-qatzip-level: Set the compression level to be used in live
-# migration. The level is an integer between 1 and 9, where 1 means
+# migration. The level is an integer between 1 and 9, where 1 means
# the best compression speed, and 9 means the best compression
-# ratio which will consume more CPU. Defaults to 1. (Since 9.2)
+# ratio which will consume more CPU. Defaults to 1. (Since 9.2)
#
# @multifd-zstd-level: Set the compression level to be used in live
# migration, the compression level is an integer between 0 and 20,
@@ -1233,9 +1233,9 @@
# more CPU. Defaults to 1. (Since 5.0)
#
# @multifd-qatzip-level: Set the compression level to be used in live
-# migration. The level is an integer between 1 and 9, where 1 means
+# migration. The level is an integer between 1 and 9, where 1 means
# the best compression speed, and 9 means the best compression
-# ratio which will consume more CPU. Defaults to 1. (Since 9.2)
+# ratio which will consume more CPU. Defaults to 1. (Since 9.2)
#
# @multifd-zstd-level: Set the compression level to be used in live
# migration, the compression level is an integer between 0 and 20,
diff --git a/qapi/qom.json b/qapi/qom.json
index 04c118e4d6..d9e1a64ce4 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -870,7 +870,7 @@
# information read from devices and switches in conjunction with
# link characteristics read from PCIe Configuration space.
# To get the full path latency from CPU to CXL attached DRAM
-# CXL device: Add the latency from CPU to Generic Port (from
+# CXL device: Add the latency from CPU to Generic Port (from
# HMAT indexed via the node ID in this SRAT structure) to
# that for CXL bus links, the latency across intermediate switches
# and from the EP port to the actual memory. Bandwidth is more
--
2.48.1
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 03/13] qapi: Move (since X.Y) to end of description
2025-05-27 7:39 [PATCH 00/13] qapi: Doc fixes and improvements Markus Armbruster
2025-05-27 7:39 ` [PATCH 01/13] qapi: Tidy up run-together sentences in doc comments Markus Armbruster
2025-05-27 7:39 ` [PATCH 02/13] qapi: Tidy up whitespace " Markus Armbruster
@ 2025-05-27 7:39 ` Markus Armbruster
2025-05-27 7:39 ` [PATCH 04/13] qapi: Avoid breaking lines within (since X.Y) Markus Armbruster
` (11 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Markus Armbruster @ 2025-05-27 7:39 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, kwolf, jsnow, vsementsov, qemu-block
By convention, we put (since X.Y) at the end of the description. Move
the ones that somehow ended up in the middle of the description to the
end.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/block-core.json | 18 +++++++++---------
qapi/net.json | 6 +++---
2 files changed, 12 insertions(+), 12 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 13223df9b4..0700bd3d46 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1322,8 +1322,8 @@
# @incremental: only copy data described by the dirty bitmap.
# (since: 2.4)
#
-# @bitmap: only copy data described by the dirty bitmap. (since: 4.2)
-# Behavior on completion is determined by the BitmapSyncMode.
+# @bitmap: only copy data described by the dirty bitmap. Behavior on
+# completion is determined by the BitmapSyncMode. (since: 4.2)
#
# Since: 1.3
##
@@ -3415,8 +3415,8 @@
# Driver specific block device options for LUKS.
#
# @key-secret: the ID of a QCryptoSecret object providing the
-# decryption key (since 2.6). Mandatory except when doing a
-# metadata-only probe of the image.
+# decryption key. Mandatory except when doing a metadata-only
+# probe of the image. (since 2.6)
#
# @header: block device holding a detached LUKS header. (since 9.0)
#
@@ -4724,11 +4724,11 @@
#
# @driver: block driver name
#
-# @node-name: the node name of the new node (Since 2.0). This option
-# is required on the top level of blockdev-add. Valid node names
-# start with an alphabetic character and may contain only
-# alphanumeric characters, '-', '.' and '_'. Their maximum length
-# is 31 characters.
+# @node-name: the node name of the new node. This option is required
+# on the top level of blockdev-add. Valid node names start with
+# an alphabetic character and may contain only alphanumeric
+# characters, '-', '.' and '_'. Their maximum length is 31
+# characters. (Since 2.0)
#
# @discard: discard-related options (default: ignore)
#
diff --git a/qapi/net.json b/qapi/net.json
index 310cc4fd19..e670efd6b0 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -150,9 +150,9 @@
# @domainname: guest-visible domain name of the virtual nameserver
# (since 3.0)
#
-# @ipv6-prefix: IPv6 network prefix (default is fec0::) (since 2.6).
-# The network prefix is given in the usual hexadecimal IPv6
-# address notation.
+# @ipv6-prefix: IPv6 network prefix (default is fec0::). The network
+# prefix is given in the usual hexadecimal IPv6 address notation.
+# (since 2.6)
#
# @ipv6-prefixlen: IPv6 network prefix length (default is 64) (since
# 2.6)
--
2.48.1
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 04/13] qapi: Avoid breaking lines within (since X.Y)
2025-05-27 7:39 [PATCH 00/13] qapi: Doc fixes and improvements Markus Armbruster
` (2 preceding siblings ...)
2025-05-27 7:39 ` [PATCH 03/13] qapi: Move (since X.Y) to end of description Markus Armbruster
@ 2025-05-27 7:39 ` Markus Armbruster
2025-05-27 7:39 ` [PATCH 05/13] qapi: Drop a problematic (Since: 2.11) from query-hotpluggable-cpus Markus Armbruster
` (10 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Markus Armbruster @ 2025-05-27 7:39 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, kwolf, jsnow, vsementsov, qemu-block
Easier on the eyes and for grep.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/block-core.json | 56 ++++++++++++++++++++++----------------------
qapi/introspect.json | 4 ++--
qapi/job.json | 12 +++++-----
qapi/machine.json | 4 ++--
qapi/migration.json | 36 ++++++++++++++--------------
qapi/net.json | 12 +++++-----
qapi/run-state.json | 4 ++--
qapi/ui.json | 4 ++--
8 files changed, 66 insertions(+), 66 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 0700bd3d46..cc48fc7122 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -31,8 +31,8 @@
# @icount: Current instruction count. Appears when execution
# record/replay is enabled. Used for "time-traveling" to match
# the moment in the recorded execution with the snapshots. This
-# counter may be obtained through @query-replay command (since
-# 5.2)
+# counter may be obtained through @query-replay command
+# (since 5.2)
#
# Since: 1.3
##
@@ -510,11 +510,11 @@
#
# @bps_max: total throughput limit during bursts, in bytes (Since 1.7)
#
-# @bps_rd_max: read throughput limit during bursts, in bytes (Since
-# 1.7)
+# @bps_rd_max: read throughput limit during bursts, in bytes
+# (Since 1.7)
#
-# @bps_wr_max: write throughput limit during bursts, in bytes (Since
-# 1.7)
+# @bps_wr_max: write throughput limit during bursts, in bytes
+# (Since 1.7)
#
# @iops_max: total I/O operations per second during bursts, in bytes
# (Since 1.7)
@@ -951,11 +951,11 @@
# @unmap_operations: The number of unmap operations performed by the
# device (Since 4.2)
#
-# @rd_total_time_ns: Total time spent on reads in nanoseconds (since
-# 0.15).
+# @rd_total_time_ns: Total time spent on reads in nanoseconds
+# (since 0.15)
#
-# @wr_total_time_ns: Total time spent on writes in nanoseconds (since
-# 0.15).
+# @wr_total_time_ns: Total time spent on writes in nanoseconds
+# (since 0.15)
#
# @zone_append_total_time_ns: Total time spent on zone append writes
# in nanoseconds (since 8.1)
@@ -1502,15 +1502,15 @@
#
# @device: the name of the device to take a snapshot of.
#
-# @node-name: graph node name to generate the snapshot from (Since
-# 2.0)
+# @node-name: graph node name to generate the snapshot from
+# (Since 2.0)
#
# @snapshot-file: the target of the new overlay image. If the file
# exists, or if it is a device, the overlay will be created in the
# existing file/device. Otherwise, a new file will be created.
#
-# @snapshot-node-name: the graph node name of the new image (Since
-# 2.0)
+# @snapshot-node-name: the graph node name of the new image
+# (Since 2.0)
#
# @format: the format of the overlay image, default is 'qcow2'.
#
@@ -1785,8 +1785,8 @@
# 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
# itself. The user needs to complete the job with the
-# block-job-complete command after getting the ready event. (Since
-# 2.0)
+# block-job-complete command after getting the ready event.
+# (Since 2.0)
#
# If the base image is smaller than top, then the base image will be
# resized to be the same size as top. If top is smaller than the base
@@ -2169,8 +2169,8 @@
# @format: the format of the new destination, default is to probe if
# @mode is 'existing', else the format of the source
#
-# @node-name: the new block driver state node name in the graph (Since
-# 2.1)
+# @node-name: the new block driver state node name in the graph
+# (Since 2.1)
#
# @replaces: with sync=full graph node name to be replaced by the new
# image when a whole image copy is done. This can be used to
@@ -2593,11 +2593,11 @@
#
# @bps_max: total throughput limit during bursts, in bytes (Since 1.7)
#
-# @bps_rd_max: read throughput limit during bursts, in bytes (Since
-# 1.7)
+# @bps_rd_max: read throughput limit during bursts, in bytes
+# (Since 1.7)
#
-# @bps_wr_max: write throughput limit during bursts, in bytes (Since
-# 1.7)
+# @bps_wr_max: write throughput limit during bursts, in bytes
+# (Since 1.7)
#
# @iops_max: total I/O operations per second during bursts, in bytes
# (Since 1.7)
@@ -3655,8 +3655,8 @@
# this feature. (since 2.5)
#
# @encrypt: Image decryption options. Mandatory for encrypted images,
-# except when doing a metadata-only probe of the image. (since
-# 2.10)
+# except when doing a metadata-only probe of the image.
+# (since 2.10)
#
# @data-file: reference to or definition of the external data file.
# This may only be specified for images that require an external
@@ -4326,8 +4326,8 @@
# @user: Ceph id name.
#
# @auth-client-required: Acceptable authentication modes. This maps
-# to Ceph configuration option "auth_client_required". (Since
-# 3.0)
+# to Ceph configuration option "auth_client_required".
+# (Since 3.0)
#
# @key-secret: ID of a QCryptoSecret object providing a key for cephx
# authentication. This maps to Ceph configuration option "key".
@@ -4581,8 +4581,8 @@
# error. During the first @reconnect-delay seconds, all requests
# are paused and will be rerun on a successful reconnect. After
# that time, any delayed requests and all future requests before a
-# successful reconnect will immediately fail. Default 0 (Since
-# 4.2)
+# successful reconnect will immediately fail. Default 0
+# (Since 4.2)
#
# @open-timeout: In seconds. If zero, the nbd driver tries the
# connection only once, and fails to open if the connection fails.
diff --git a/qapi/introspect.json b/qapi/introspect.json
index 01bb242947..95724ee2d2 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -154,8 +154,8 @@
#
# Additional SchemaInfo members for meta-type 'enum'.
#
-# @members: the enum type's members, in no particular order (since
-# 6.2).
+# @members: the enum type's members, in no particular order.
+# (since 6.2)
#
# @values: the enumeration type's member names, in no particular
# order. Redundant with @members. Just for backward
diff --git a/qapi/job.json b/qapi/job.json
index c53c96cce8..9ddba537db 100644
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -20,14 +20,14 @@
#
# @create: image creation job type, see "blockdev-create" (since 3.0)
#
-# @amend: image options amend job type, see "x-blockdev-amend" (since
-# 5.1)
+# @amend: image options amend job type, see "x-blockdev-amend"
+# (since 5.1)
#
-# @snapshot-load: snapshot load job type, see "snapshot-load" (since
-# 6.0)
+# @snapshot-load: snapshot load job type, see "snapshot-load"
+# (since 6.0)
#
-# @snapshot-save: snapshot save job type, see "snapshot-save" (since
-# 6.0)
+# @snapshot-save: snapshot save job type, see "snapshot-save"
+# (since 6.0)
#
# @snapshot-delete: snapshot delete job type, see "snapshot-delete"
# (since 6.0)
diff --git a/qapi/machine.json b/qapi/machine.json
index 1d60693b65..47e915a2e3 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -182,8 +182,8 @@
# @default-cpu-type: default CPU model typename if none is requested
# via the -cpu argument. (since 4.2)
#
-# @default-ram-id: the default ID of initial RAM memory backend (since
-# 5.2)
+# @default-ram-id: the default ID of initial RAM memory backend
+# (since 5.2)
#
# @acpi: machine type supports ACPI (since 8.0)
#
diff --git a/qapi/migration.json b/qapi/migration.json
index 83afe17cec..0e5a656cc9 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -57,8 +57,8 @@
#
# @dirty-sync-missed-zero-copy: Number of times dirty RAM
# synchronization could not avoid copying dirty pages. This is
-# between 0 and @dirty-sync-count * @multifd-channels. (since
-# 7.1)
+# between 0 and @dirty-sync-count * @multifd-channels.
+# (since 7.1)
#
# Since: 0.14
##
@@ -137,16 +137,16 @@
#
# @active: in the process of doing migration.
#
-# @postcopy-active: like active, but now in postcopy mode. (since
-# 2.5)
+# @postcopy-active: like active, but now in postcopy mode.
+# (since 2.5)
#
# @postcopy-paused: during postcopy but paused. (since 3.0)
#
# @postcopy-recover-setup: setup phase for a postcopy recovery
# process, preparing for a recovery phase to start. (since 9.1)
#
-# @postcopy-recover: trying to recover from a paused postcopy. (since
-# 3.0)
+# @postcopy-recover: trying to recover from a paused postcopy.
+# (since 3.0)
#
# @completed: migration is finished.
#
@@ -422,8 +422,8 @@
# for precopy. (since 2.10)
#
# @pause-before-switchover: Pause outgoing migration before
-# serialising device state and before disabling block IO (since
-# 2.11)
+# serialising device state and before disabling block IO
+# (since 2.11)
#
# @multifd: Use more than one fd for migration (since 4.0)
#
@@ -697,8 +697,8 @@
# @alias: An alias name for migration (for example the bitmap name on
# the opposite site).
#
-# @transform: Allows the modification of the migrated bitmap. (since
-# 6.0)
+# @transform: Allows the modification of the migrated bitmap.
+# (since 6.0)
#
# Since: 5.2
##
@@ -770,8 +770,8 @@
# specified by @cpu-throttle-increment and the one generated by
# ideal CPU percentage. Therefore, it is compatible to
# traditional throttling, meanwhile the throttle increment won't
-# be excessive at tail stage. The default value is false. (Since
-# 5.1)
+# be excessive at tail stage. The default value is false.
+# (Since 5.1)
#
# @tls-creds: ID of the 'tls-creds' object that provides credentials
# for establishing a TLS connection over the migration data
@@ -951,8 +951,8 @@
# specified by @cpu-throttle-increment and the one generated by
# ideal CPU percentage. Therefore, it is compatible to
# traditional throttling, meanwhile the throttle increment won't
-# be excessive at tail stage. The default value is false. (Since
-# 5.1)
+# be excessive at tail stage. The default value is false.
+# (Since 5.1)
#
# @tls-creds: ID of the 'tls-creds' object that provides credentials
# for establishing a TLS connection over the migration data
@@ -1148,8 +1148,8 @@
# percentage. The default value is 50. (Since 5.0)
#
# @cpu-throttle-initial: Initial percentage of time guest cpus are
-# throttled when migration auto-converge is activated. (Since
-# 2.7)
+# throttled when migration auto-converge is activated.
+# (Since 2.7)
#
# @cpu-throttle-increment: throttle percentage increase each time
# auto-converge detects that migration is not making progress.
@@ -1165,8 +1165,8 @@
# specified by @cpu-throttle-increment and the one generated by
# ideal CPU percentage. Therefore, it is compatible to
# traditional throttling, meanwhile the throttle increment won't
-# be excessive at tail stage. The default value is false. (Since
-# 5.1)
+# be excessive at tail stage. The default value is false.
+# (Since 5.1)
#
# @tls-creds: ID of the 'tls-creds' object that provides credentials
# for establishing a TLS connection over the migration data
diff --git a/qapi/net.json b/qapi/net.json
index e670efd6b0..97ea183981 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -154,8 +154,8 @@
# prefix is given in the usual hexadecimal IPv6 address notation.
# (since 2.6)
#
-# @ipv6-prefixlen: IPv6 network prefix length (default is 64) (since
-# 2.6)
+# @ipv6-prefixlen: IPv6 network prefix length (default is 64)
+# (since 2.6)
#
# @ipv6-host: guest-visible IPv6 address of the host (since 2.6)
#
@@ -387,8 +387,8 @@
#
# @hubid: hub identifier number
#
-# @netdev: used to connect hub to a netdev instead of a device (since
-# 2.12)
+# @netdev: used to connect hub to a netdev instead of a device
+# (since 2.12)
#
# Since: 1.2
##
@@ -510,8 +510,8 @@
# @queues: number of queues to be created for multiqueue vhost-vdpa
# (default: 1)
#
-# @x-svq: Start device with (experimental) shadow virtqueue. (Since
-# 7.1) (default: false)
+# @x-svq: Start device with (experimental) shadow virtqueue.
+# (Since 7.1) (default: false)
#
# Features:
#
diff --git a/qapi/run-state.json b/qapi/run-state.json
index ce95cfa46b..4e44da63a0 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -365,8 +365,8 @@
# @shutdown: Shutdown the VM and exit, according to the shutdown
# action
#
-# @exit-failure: Shutdown the VM and exit with nonzero status (since
-# 7.1)
+# @exit-failure: Shutdown the VM and exit with nonzero status
+# (since 7.1)
#
# Since: 6.0
##
diff --git a/qapi/ui.json b/qapi/ui.json
index c536d4e524..3991329668 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -175,8 +175,8 @@
# @filename: the path of a new file to store the image
#
# @device: ID of the display device that should be dumped. If this
-# parameter is missing, the primary display will be used. (Since
-# 2.12)
+# parameter is missing, the primary display will be used.
+# (Since 2.12)
#
# @head: head to use in case the device supports multiple heads. If
# this parameter is missing, head #0 will be used. Also note that
--
2.48.1
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 05/13] qapi: Drop a problematic (Since: 2.11) from query-hotpluggable-cpus
2025-05-27 7:39 [PATCH 00/13] qapi: Doc fixes and improvements Markus Armbruster
` (3 preceding siblings ...)
2025-05-27 7:39 ` [PATCH 04/13] qapi: Avoid breaking lines within (since X.Y) Markus Armbruster
@ 2025-05-27 7:39 ` Markus Armbruster
2025-05-27 7:39 ` [PATCH 06/13] qapi: Correct spelling of QEMU in doc comments Markus Armbruster
` (9 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Markus Armbruster @ 2025-05-27 7:39 UTC (permalink / raw)
To: qemu-devel
Cc: eblake, kwolf, jsnow, vsementsov, qemu-block, David Hildenbrand
There is a (Since: 2.11) in a query-hotpluggable-cpus example.
Versioning information ought to be in the command description, not
examples. The command description is basically empty (there is a TODO
about it).
What exactly didn't work before 2.11 is not quite clear from the
documentation. The example was added in commit 4dc3b151882 (s390x:
implement query-hotpluggable-cpus), which suggests the command failed
for the s390x target until then. This was almost eight years ago, and
I doubt anyone still cares about this detail. Simply delete
the problematic (Since: 2.11).
Cc: David Hildenbrand <david@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/machine.json | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/qapi/machine.json b/qapi/machine.json
index 47e915a2e3..ab4e0585f8 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1089,7 +1089,7 @@
# :annotated:
#
# For s390x-virtio-ccw machine type started with
-# ``-smp 1,maxcpus=2 -cpu qemu`` (Since: 2.11)::
+# ``-smp 1,maxcpus=2 -cpu qemu``::
#
# -> { "execute": "query-hotpluggable-cpus" }
# <- {"return": [
--
2.48.1
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 06/13] qapi: Correct spelling of QEMU in doc comments
2025-05-27 7:39 [PATCH 00/13] qapi: Doc fixes and improvements Markus Armbruster
` (4 preceding siblings ...)
2025-05-27 7:39 ` [PATCH 05/13] qapi: Drop a problematic (Since: 2.11) from query-hotpluggable-cpus Markus Armbruster
@ 2025-05-27 7:39 ` Markus Armbruster
2025-05-27 7:39 ` [PATCH 07/13] qapi: Fix capitalization " Markus Armbruster
` (8 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Markus Armbruster @ 2025-05-27 7:39 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, kwolf, jsnow, vsementsov, qemu-block
Improve awkward phrasing in migrate-incoming While there.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/audio.json | 8 ++++----
qapi/block-core.json | 10 +++++-----
qapi/block-export.json | 2 +-
qapi/char.json | 6 +++---
qapi/introspect.json | 4 ++--
qapi/migration.json | 8 ++++----
qapi/run-state.json | 6 +++---
qapi/transaction.json | 2 +-
qapi/uefi.json | 2 +-
qapi/ui.json | 4 ++--
10 files changed, 26 insertions(+), 26 deletions(-)
diff --git a/qapi/audio.json b/qapi/audio.json
index 49633cf317..67f36f1cfe 100644
--- a/qapi/audio.json
+++ b/qapi/audio.json
@@ -309,9 +309,9 @@
#
# @name: name of the sink/source to use
#
-# @stream-name: name of the PulseAudio stream created by qemu. Can be
+# @stream-name: name of the PulseAudio stream created by QEMU. Can be
# used to identify the stream in PulseAudio when you create
-# multiple PulseAudio devices or run multiple qemu instances
+# multiple PulseAudio devices or run multiple QEMU instances
# (default: audiodev's id, since 4.2)
#
# @latency: latency you want PulseAudio to achieve in microseconds
@@ -353,9 +353,9 @@
#
# @name: name of the sink/source to use
#
-# @stream-name: name of the PipeWire stream created by qemu. Can be
+# @stream-name: name of the PipeWire stream created by QEMU. Can be
# used to identify the stream in PipeWire when you create multiple
-# PipeWire devices or run multiple qemu instances (default:
+# PipeWire devices or run multiple QEMU instances (default:
# audiodev's id)
#
# @latency: latency you want PipeWire to achieve in microseconds
diff --git a/qapi/block-core.json b/qapi/block-core.json
index cc48fc7122..b6447e847e 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -2030,7 +2030,7 @@
#
# @id: Block graph node identifier. This @id is generated only for
# x-debug-query-block-graph and does not relate to any other
-# identifiers in Qemu.
+# identifiers in QEMU.
#
# @type: Type of graph node. Can be one of block-backend, block-job
# or block-driver-state.
@@ -2794,7 +2794,7 @@
# The node that receives the data is called the top image, can be
# located in any part of the chain (but always above the base image;
# see below) and can be specified using its device or node name.
-# Earlier qemu versions only allowed 'device' to name the top level
+# Earlier QEMU versions only allowed 'device' to name the top level
# node; presence of the 'base-node' parameter during introspection can
# be used as a witness of the enhanced semantics of 'device'.
#
@@ -3196,7 +3196,7 @@
#
# Selects the AIO backend to handle I/O requests
#
-# @threads: Use qemu's thread pool
+# @threads: Use QEMU's thread pool
#
# @native: Use native AIO backend (only Linux and Windows)
#
@@ -5157,10 +5157,10 @@
##
# @BlockdevQcow2Version:
#
-# @v2: The original QCOW2 format as introduced in qemu 0.10 (version
+# @v2: The original QCOW2 format as introduced in QEMU 0.10 (version
# 2)
#
-# @v3: The extended QCOW2 format as introduced in qemu 1.1 (version 3)
+# @v3: The extended QCOW2 format as introduced in QEMU 1.1 (version 3)
#
# Since: 2.12
##
diff --git a/qapi/block-export.json b/qapi/block-export.json
index 04190b503c..ed4deb54db 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -169,7 +169,7 @@
# @growable: Whether writes beyond the EOF should grow the block node
# accordingly. (default: false)
#
-# @allow-other: If this is off, only qemu's user is allowed access to
+# @allow-other: If this is off, only QEMU's user is allowed access to
# this export. That cannot be changed even with chmod or chown.
# Enabling this option will allow other users access to the export
# with the FUSE mount option "allow_other". Note that using
diff --git a/qapi/char.json b/qapi/char.json
index 9ad9d11cf6..f1d8b503dd 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -351,7 +351,7 @@
# Configuration info for stdio chardevs.
#
# @signal: Allow signals (such as SIGINT triggered by ^C) be delivered
-# to qemu. Default: true.
+# to QEMU. Default: true.
#
# Since: 1.5
##
@@ -443,7 +443,7 @@
##
# @ChardevQemuVDAgent:
#
-# Configuration info for qemu vdagent implementation.
+# Configuration info for QEMU vdagent implementation.
#
# @mouse: enable/disable mouse, default is enabled.
#
@@ -656,7 +656,7 @@
##
# @ChardevQemuVDAgentWrapper:
#
-# @data: Configuration info for qemu vdagent implementation
+# @data: Configuration info for QEMU vdagent implementation
#
# Since: 6.1
##
diff --git a/qapi/introspect.json b/qapi/introspect.json
index 95724ee2d2..e9e0297282 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -26,9 +26,9 @@
# the QAPI schema.
#
# Furthermore, while we strive to keep the QMP wire format
-# backwards-compatible across qemu versions, the introspection output
+# backwards-compatible across QEMU versions, the introspection output
# is not guaranteed to have the same stability. For example, one
-# version of qemu may list an object member as an optional
+# version of QEMU may list an object member as an optional
# non-variant, while another lists the same member only through the
# object's variants; or the type of a member may change from a generic
# string into a specific enum or from one specific type into an
diff --git a/qapi/migration.json b/qapi/migration.json
index 0e5a656cc9..461f9f0892 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -415,7 +415,7 @@
# on secondary side, this process is called COarse-Grain LOck
# Stepping (COLO) for Non-stop Service. (since 2.8)
#
-# @release-ram: if enabled, qemu will free the migrated ram pages on
+# @release-ram: if enabled, QEMU will free the migrated ram pages on
# the source during postcopy-ram migration. (since 2.9)
#
# @return-path: If enabled, migration will use the return path even
@@ -1500,7 +1500,7 @@
##
# @x-colo-lost-heartbeat:
#
-# Tell qemu that heartbeat is lost, request it to do takeover
+# 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
@@ -1729,8 +1729,8 @@
##
# @migrate-incoming:
#
-# Start an incoming migration, the 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
diff --git a/qapi/run-state.json b/qapi/run-state.json
index 4e44da63a0..eee61edff4 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -135,19 +135,19 @@
##
# @SHUTDOWN:
#
-# Emitted when the virtual machine has shut down, indicating that qemu
+# Emitted when the virtual machine has shut down, indicating that QEMU
# is about to exit.
#
# @guest: If true, the shutdown was triggered by a guest request (such
# as a guest-initiated ACPI shutdown request or other
# hardware-specific action) rather than a host request (such as
-# sending qemu a SIGINT). (since 2.10)
+# sending QEMU a SIGINT). (since 2.10)
#
# @reason: The @ShutdownCause which resulted in the SHUTDOWN.
# (since 4.0)
#
# .. note:: If the command-line option ``-no-shutdown`` has been
-# specified, qemu will not exit, and a STOP event will eventually
+# specified, QEMU will not exit, and a STOP event will eventually
# follow the SHUTDOWN event.
#
# Since: 0.12
diff --git a/qapi/transaction.json b/qapi/transaction.json
index 021e383496..5c3394919e 100644
--- a/qapi/transaction.json
+++ b/qapi/transaction.json
@@ -223,7 +223,7 @@
# exists, the request will be rejected. Only some image formats
# support it, for example, qcow2, and rbd,
#
-# On failure, qemu will try delete the newly created internal snapshot
+# On failure, QEMU will try delete the newly created internal snapshot
# in the transaction. When an I/O error occurs during deletion, the
# user needs to fix it later with qemu-img or other command.
#
diff --git a/qapi/uefi.json b/qapi/uefi.json
index bdfcabe1df..6592183d6c 100644
--- a/qapi/uefi.json
+++ b/qapi/uefi.json
@@ -5,7 +5,7 @@
##
# = UEFI Variable Store
#
-# The qemu efi variable store implementation (hw/uefi/) uses this to
+# The QEMU efi variable store implementation (hw/uefi/) uses this to
# store non-volatile variables in json format on disk.
#
# This is an existing format already supported by (at least) two other
diff --git a/qapi/ui.json b/qapi/ui.json
index 3991329668..5939947b76 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -1526,12 +1526,12 @@
#
# Display (user interface) options.
#
-# @type: Which DisplayType qemu should use.
+# @type: Which DisplayType QEMU should use.
#
# @full-screen: Start user interface in fullscreen mode
# (default: off).
#
-# @window-close: Allow to quit qemu with window close button
+# @window-close: Allow to quit QEMU with window close button
# (default: on).
#
# @show-cursor: Force showing the mouse cursor (default: off).
--
2.48.1
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 07/13] qapi: Fix capitalization in doc comments
2025-05-27 7:39 [PATCH 00/13] qapi: Doc fixes and improvements Markus Armbruster
` (5 preceding siblings ...)
2025-05-27 7:39 ` [PATCH 06/13] qapi: Correct spelling of QEMU in doc comments Markus Armbruster
@ 2025-05-27 7:39 ` Markus Armbruster
2025-05-27 7:39 ` [PATCH 08/13] qapi: Use proper markup instead of CAPS for emphasis " Markus Armbruster
` (7 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Markus Armbruster @ 2025-05-27 7:39 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, kwolf, jsnow, vsementsov, qemu-block
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/block-core.json | 6 +++---
qapi/block.json | 2 +-
qapi/cryptodev.json | 2 +-
qapi/cxl.json | 2 +-
qapi/machine.json | 2 +-
qapi/misc-target.json | 2 +-
qapi/run-state.json | 2 +-
qapi/transaction.json | 2 +-
8 files changed, 10 insertions(+), 10 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index b6447e847e..f0faca1054 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1337,7 +1337,7 @@
# bitmap when used for data copy operations.
#
# @on-success: The bitmap is only synced when the operation is
-# successful. This is the behavior always used for 'INCREMENTAL'
+# successful. This is the behavior always used for incremental
# backups.
#
# @never: The bitmap is never synchronized with the operation, and is
@@ -1589,7 +1589,7 @@
#
# @bitmap-mode: Specifies the type of data the bitmap should contain
# after the operation concludes. Must be present if a bitmap was
-# provided, Must NOT be present otherwise. (Since 4.2)
+# provided, must NOT be present otherwise. (Since 4.2)
#
# @compress: true to compress data, if the target format supports it.
# (default: false) (since 2.8)
@@ -1840,7 +1840,7 @@
# @speed: the maximum speed, in bytes per second
#
# @on-error: the action to take on an error. 'ignore' means that the
-# request should be retried. (default: report; Since: 5.0)
+# request should be retried. (default: report; since: 5.0)
#
# @filter-node-name: the node name that should be assigned to the
# filter driver that the commit job inserts into the graph above
diff --git a/qapi/block.json b/qapi/block.json
index e66666f5c6..c07941ee5b 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -48,7 +48,7 @@
##
# @FloppyDriveType:
#
-# Type of Floppy drive to be emulated by the Floppy Disk Controller.
+# Type of floppy drive to be emulated by the Floppy Disk Controller.
#
# @144: 1.44MB 3.5" drive
#
diff --git a/qapi/cryptodev.json b/qapi/cryptodev.json
index 04d0e21d20..4d4428a25a 100644
--- a/qapi/cryptodev.json
+++ b/qapi/cryptodev.json
@@ -15,7 +15,7 @@
#
# @sym: symmetric encryption
#
-# @asym: asymmetric Encryption
+# @asym: asymmetric encryption
#
# Since: 8.0
##
diff --git a/qapi/cxl.json b/qapi/cxl.json
index dd947d3bbc..8f2e9237b1 100644
--- a/qapi/cxl.json
+++ b/qapi/cxl.json
@@ -117,7 +117,7 @@
# @nibble-mask: Identifies one or more nibbles that the error affects
#
# @bank-group: Bank group of the memory event location, incorporating
-# a number of Banks.
+# a number of banks.
#
# @bank: Bank of the memory event location. A single bank is accessed
# per read or write of the memory.
diff --git a/qapi/machine.json b/qapi/machine.json
index ab4e0585f8..d1e37ebcb2 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -811,7 +811,7 @@
#
# @policy: the write policy, none/write-back/write-through.
#
-# @line: the cache Line size in bytes.
+# @line: the cache line size in bytes.
#
# Since: 5.0
##
diff --git a/qapi/misc-target.json b/qapi/misc-target.json
index f7ec695caa..7ed972493c 100644
--- a/qapi/misc-target.json
+++ b/qapi/misc-target.json
@@ -186,7 +186,7 @@
#
# @cbitpos: C-bit location in page table entry
#
-# @reduced-phys-bits: Number of physical Address bit reduction when
+# @reduced-phys-bits: Number of physical address bit reduction when
# SEV is enabled
#
# Since: 2.12
diff --git a/qapi/run-state.json b/qapi/run-state.json
index eee61edff4..dbf25c7392 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -62,7 +62,7 @@
##
# @ShutdownCause:
#
-# An enumeration of reasons for a Shutdown.
+# An enumeration of reasons for a shutdown.
#
# @none: No shutdown request pending
#
diff --git a/qapi/transaction.json b/qapi/transaction.json
index 5c3394919e..9d9e7af26c 100644
--- a/qapi/transaction.json
+++ b/qapi/transaction.json
@@ -21,7 +21,7 @@
##
# @ActionCompletionMode:
#
-# An enumeration of Transactional completion modes.
+# An enumeration of transactional completion modes.
#
# @individual: Do not attempt to cancel any other Actions if any
# Actions fail after the Transaction request succeeds. All
--
2.48.1
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 08/13] qapi: Use proper markup instead of CAPS for emphasis in doc comments
2025-05-27 7:39 [PATCH 00/13] qapi: Doc fixes and improvements Markus Armbruster
` (6 preceding siblings ...)
2025-05-27 7:39 ` [PATCH 07/13] qapi: Fix capitalization " Markus Armbruster
@ 2025-05-27 7:39 ` Markus Armbruster
2025-05-27 7:39 ` [PATCH 09/13] qapi: Spell JSON null correctly in blockdev-reopen documentation Markus Armbruster
` (6 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Markus Armbruster @ 2025-05-27 7:39 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, kwolf, jsnow, vsementsov, qemu-block
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/block-core.json | 2 +-
qapi/dump.json | 6 +++---
qapi/migration.json | 26 +++++++++++++-------------
qapi/misc.json | 4 ++--
4 files changed, 19 insertions(+), 19 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index f0faca1054..7b0548dc2e 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1589,7 +1589,7 @@
#
# @bitmap-mode: Specifies the type of data the bitmap should contain
# after the operation concludes. Must be present if a bitmap was
-# provided, must NOT be present otherwise. (Since 4.2)
+# provided, must **not** be present otherwise. (Since 4.2)
#
# @compress: true to compress data, if the target format supports it.
# (default: false) (since 2.8)
diff --git a/qapi/dump.json b/qapi/dump.json
index d7826c0e32..8ec95ef76b 100644
--- a/qapi/dump.json
+++ b/qapi/dump.json
@@ -54,9 +54,9 @@
# @paging: if true, do paging to get guest's memory mapping. This
# allows using gdb to process the core file.
#
-# IMPORTANT: this option can make QEMU allocate several gigabytes
-# of RAM. This can happen for a large guest, or a malicious guest
-# pretending to be large.
+# **Important**: this option can make QEMU allocate several
+# gigabytes of RAM. This can happen for a large guest, or a
+# malicious guest pretending to be large.
#
# Also, paging=true has the following limitations:
#
diff --git a/qapi/migration.json b/qapi/migration.json
index 461f9f0892..f1e6daa58b 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -407,7 +407,7 @@
# @postcopy-ram: Start executing on the migration target before all of
# RAM has been migrated, pulling the remaining pages along as
# needed. The capacity must have the same setting on both source
-# and target or migration will not even start. NOTE: If the
+# and target or migration will not even start. **Note:** if the
# migration fails during postcopy the VM will fail. (since 2.6)
#
# @x-colo: If enabled, migration will never end, and the state of the
@@ -801,10 +801,10 @@
# (Since 2.8)
#
# @avail-switchover-bandwidth: to set the available bandwidth that
-# migration can use during switchover phase. NOTE! This does not
-# limit the bandwidth during switchover, but only for calculations
-# when making decisions to switchover. By default, this value is
-# zero, which means QEMU will estimate the bandwidth
+# migration can use during switchover phase. **Note:** this does
+# not limit the bandwidth during switchover, but only for
+# calculations when making decisions to switchover. By default,
+# this value is zero, which means QEMU will estimate the bandwidth
# automatically. This can be set when the estimated value is not
# accurate, while the user is able to guarantee such bandwidth is
# available when switching over. When specified correctly, this
@@ -982,10 +982,10 @@
# (Since 2.8)
#
# @avail-switchover-bandwidth: to set the available bandwidth that
-# migration can use during switchover phase. NOTE! This does not
-# limit the bandwidth during switchover, but only for calculations
-# when making decisions to switchover. By default, this value is
-# zero, which means QEMU will estimate the bandwidth
+# migration can use during switchover phase. **Note:** this does
+# not limit the bandwidth during switchover, but only for
+# calculations when making decisions to switchover. By default,
+# this value is zero, which means QEMU will estimate the bandwidth
# automatically. This can be set when the estimated value is not
# accurate, while the user is able to guarantee such bandwidth is
# available when switching over. When specified correctly, this
@@ -1192,10 +1192,10 @@
# (Since 2.8)
#
# @avail-switchover-bandwidth: to set the available bandwidth that
-# migration can use during switchover phase. NOTE! This does not
-# limit the bandwidth during switchover, but only for calculations
-# when making decisions to switchover. By default, this value is
-# zero, which means QEMU will estimate the bandwidth
+# migration can use during switchover phase. **Note:** this does
+# not limit the bandwidth during switchover, but only for
+# calculations when making decisions to switchover. By default,
+# this value is zero, which means QEMU will estimate the bandwidth
# automatically. This can be set when the estimated value is not
# accurate, while the user is able to guarantee such bandwidth is
# available when switching over. When specified correctly, this
diff --git a/qapi/misc.json b/qapi/misc.json
index 559b66f201..83e5bdadca 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -222,8 +222,8 @@
# .. note:: This command only exists as a stop-gap. Its use is highly
# discouraged. The semantics of this command are not guaranteed:
# this means that command names, arguments and responses can change
-# or be removed at ANY time. Applications that rely on long term
-# stability guarantees should NOT use this command.
+# or be removed at **any** time. Applications that rely on long
+# term stability guarantees should **not** use this command.
#
# Known limitations:
#
--
2.48.1
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 09/13] qapi: Spell JSON null correctly in blockdev-reopen documentation
2025-05-27 7:39 [PATCH 00/13] qapi: Doc fixes and improvements Markus Armbruster
` (7 preceding siblings ...)
2025-05-27 7:39 ` [PATCH 08/13] qapi: Use proper markup instead of CAPS for emphasis " Markus Armbruster
@ 2025-05-27 7:39 ` Markus Armbruster
2025-05-27 7:39 ` [PATCH 10/13] qapi: Refer to job-FOO instead of deprecated block-job-FOO in docs Markus Armbruster
` (5 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Markus Armbruster @ 2025-05-27 7:39 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, kwolf, jsnow, vsementsov, qemu-block
The doc comment misspells JSON null as NULL. Fix that.
Cc: Kevin Wolf <kwolf@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/block-core.json | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 7b0548dc2e..f8f89ee2d7 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -4947,7 +4947,7 @@
# 3) A reference to a different node: the current child is replaced
# with the specified one.
#
-# 4) NULL: the current child (if any) is detached.
+# 4) null: the current child (if any) is detached.
#
# Options (1) and (2) are supported in all cases. Option (3) is
# supported for @file and @backing, and option (4) for @backing only.
--
2.48.1
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 10/13] qapi: Refer to job-FOO instead of deprecated block-job-FOO in docs
2025-05-27 7:39 [PATCH 00/13] qapi: Doc fixes and improvements Markus Armbruster
` (8 preceding siblings ...)
2025-05-27 7:39 ` [PATCH 09/13] qapi: Spell JSON null correctly in blockdev-reopen documentation Markus Armbruster
@ 2025-05-27 7:39 ` Markus Armbruster
2025-05-27 7:39 ` [PATCH 11/13] qapi: Mention both job-cancel and block-job-cancel in doc comments Markus Armbruster
` (4 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Markus Armbruster @ 2025-05-27 7:39 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, kwolf, jsnow, vsementsov, qemu-block
We deprecated several block-job-FOO commands in commit
b836bf2ab68 (qapi/block-core: deprecate some block-job- APIs). Update
the doc comments to refer to their replacements instead.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/block-core.json | 57 ++++++++++++++++++++++----------------------
1 file changed, 28 insertions(+), 29 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index f8f89ee2d7..6e5b90d5df 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1606,16 +1606,16 @@
# copy-before-write jobs; defaults to break-guest-write. (Since 10.1)
#
# @auto-finalize: When false, this job will wait in a PENDING state
-# after it has finished its work, waiting for @block-job-finalize
-# before making any block graph changes. When true, this job will
+# after it has finished its work, waiting for @job-finalize before
+# making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 2.12)
#
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
-# @block-job-dismiss. When true, this job will automatically
-# disappear from the query list without user intervention.
-# Defaults to true. (Since 2.12)
+# @job-dismiss. When true, this job will automatically disappear
+# from the query list without user intervention. Defaults to
+# true. (Since 2.12)
#
# @filter-node-name: the node name that should be assigned to the
# filter driver that the backup job inserts into the graph above
@@ -1785,8 +1785,7 @@
# 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
# itself. The user needs to complete the job with the
-# block-job-complete command after getting the ready event.
-# (Since 2.0)
+# job-complete command after getting the ready event. (Since 2.0)
#
# If the base image is smaller than top, then the base image will be
# resized to be the same size as top. If top is smaller than the base
@@ -1848,16 +1847,16 @@
# autogenerated. (Since: 2.9)
#
# @auto-finalize: When false, this job will wait in a PENDING state
-# after it has finished its work, waiting for @block-job-finalize
-# before making any block graph changes. When true, this job will
+# after it has finished its work, waiting for @job-finalize before
+# making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 3.1)
#
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
-# @block-job-dismiss. When true, this job will automatically
-# disappear from the query list without user intervention.
-# Defaults to true. (Since 3.1)
+# @job-dismiss. When true, this job will automatically disappear
+# from the query list without user intervention. Defaults to
+# true. (Since 3.1)
#
# Features:
#
@@ -2212,16 +2211,16 @@
# 'background' (Since: 3.0)
#
# @auto-finalize: When false, this job will wait in a PENDING state
-# after it has finished its work, waiting for @block-job-finalize
-# before making any block graph changes. When true, this job will
+# after it has finished its work, waiting for @job-finalize before
+# making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 3.1)
#
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
-# @block-job-dismiss. When true, this job will automatically
-# disappear from the query list without user intervention.
-# Defaults to true. (Since 3.1)
+# @job-dismiss. When true, this job will automatically disappear
+# from the query list without user intervention. Defaults to
+# true. (Since 3.1)
#
# Since: 1.3
##
@@ -2531,16 +2530,16 @@
# 'background' (Since: 3.0)
#
# @auto-finalize: When false, this job will wait in a PENDING state
-# after it has finished its work, waiting for @block-job-finalize
-# before making any block graph changes. When true, this job will
+# after it has finished its work, waiting for @job-finalize before
+# making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 3.1)
#
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
-# @block-job-dismiss. When true, this job will automatically
-# disappear from the query list without user intervention.
-# Defaults to true. (Since 3.1)
+# @job-dismiss. When true, this job will automatically disappear
+# from the query list without user intervention. Defaults to
+# true. (Since 3.1)
#
# @target-is-zero: Assume the destination reads as all zeroes before
# the mirror started. Setting this to true can speed up the
@@ -2859,16 +2858,16 @@
# autogenerated. (Since: 6.0)
#
# @auto-finalize: When false, this job will wait in a PENDING state
-# after it has finished its work, waiting for @block-job-finalize
-# before making any block graph changes. When true, this job will
+# after it has finished its work, waiting for @job-finalize before
+# making any block graph changes. When true, this job will
# automatically perform its abort or commit actions. Defaults to
# true. (Since 3.1)
#
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
-# @block-job-dismiss. When true, this job will automatically
-# disappear from the query list without user intervention.
-# Defaults to true. (Since 3.1)
+# @job-dismiss. When true, this job will automatically disappear
+# from the query list without user intervention. Defaults to
+# true. (Since 3.1)
#
# Errors:
# - If @device does not exist, DeviceNotFound.
@@ -3077,7 +3076,7 @@
# This command will refuse to operate on any job that has not yet
# reached its terminal state, JOB_STATUS_CONCLUDED. For jobs that
# make use of the BLOCK_JOB_READY event, block-job-cancel or
-# block-job-complete will still need to be used as appropriate.
+# job-complete will still need to be used as appropriate.
#
# @id: The job identifier.
#
@@ -5866,7 +5865,7 @@
# @BLOCK_JOB_PENDING:
#
# Emitted when a block job is awaiting explicit authorization to
-# finalize graph changes via @block-job-finalize. If this job is part
+# finalize graph changes via @job-finalize. If this job is part
# of a transaction, it will not emit this event until the transaction
# has converged first.
#
--
2.48.1
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 11/13] qapi: Mention both job-cancel and block-job-cancel in doc comments
2025-05-27 7:39 [PATCH 00/13] qapi: Doc fixes and improvements Markus Armbruster
` (9 preceding siblings ...)
2025-05-27 7:39 ` [PATCH 10/13] qapi: Refer to job-FOO instead of deprecated block-job-FOO in docs Markus Armbruster
@ 2025-05-27 7:39 ` Markus Armbruster
2025-05-27 7:39 ` [PATCH 12/13] qapi: Tidy up references to job state CONCLUDED Markus Armbruster
` (3 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Markus Armbruster @ 2025-05-27 7:39 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, kwolf, jsnow, vsementsov, qemu-block
Several doc comments mention block-job-cancel where the more generic
job-cancel would also work. Adjust them to mention both.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/block-core.json | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 6e5b90d5df..ad6de151c8 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1894,7 +1894,7 @@
# 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 block-job-cancel command.
+# using the job-cancel or block-job-cancel command.
#
# Features:
#
@@ -1925,7 +1925,7 @@
# 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 block-job-cancel command.
+# using the job-cancel or block-job-cancel command.
#
# Errors:
# - If @device is not a valid block device, DeviceNotFound
@@ -2788,7 +2788,7 @@
# immediately once streaming has started. The status of ongoing block
# streaming operations can be checked with query-block-jobs. The
# operation can be stopped before it has completed using the
-# block-job-cancel command.
+# job-cancel or block-job-cancel command.
#
# The node that receives the data is called the top image, can be
# located in any part of the chain (but always above the base image;
@@ -3075,8 +3075,8 @@
#
# This command will refuse to operate on any job that has not yet
# reached its terminal state, JOB_STATUS_CONCLUDED. For jobs that
-# make use of the BLOCK_JOB_READY event, block-job-cancel or
-# job-complete will still need to be used as appropriate.
+# make use of the BLOCK_JOB_READY event, job-cancel, block-job-cancel
+# or job-complete will still need to be used as appropriate.
#
# @id: The job identifier.
#
--
2.48.1
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 12/13] qapi: Tidy up references to job state CONCLUDED
2025-05-27 7:39 [PATCH 00/13] qapi: Doc fixes and improvements Markus Armbruster
` (10 preceding siblings ...)
2025-05-27 7:39 ` [PATCH 11/13] qapi: Mention both job-cancel and block-job-cancel in doc comments Markus Armbruster
@ 2025-05-27 7:39 ` Markus Armbruster
2025-05-27 7:39 ` [PATCH 13/13] qapi: Improve documentation around job state @concluded Markus Armbruster
` (2 subsequent siblings)
14 siblings, 0 replies; 16+ messages in thread
From: Markus Armbruster @ 2025-05-27 7:39 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, kwolf, jsnow, vsementsov, qemu-block
When talking about the job state machine, we refer to the states like
READY, ABORTING, CONCLUDED, and so forth. Except in two places, where
we use JOB_STATUS_CONCLUDED. Replace by CONCLUDED for consistency.
We should arguably use the JobStatus enum values instead. Left for
another day.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/block-core.json | 6 +++---
qapi/job.json | 6 +++---
2 files changed, 6 insertions(+), 6 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index ad6de151c8..da390f85ac 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -3074,9 +3074,9 @@
# jobs.
#
# This command will refuse to operate on any job that has not yet
-# reached its terminal state, JOB_STATUS_CONCLUDED. For jobs that
-# make use of the BLOCK_JOB_READY event, job-cancel, block-job-cancel
-# or job-complete will still need to be used as appropriate.
+# reached its terminal state, CONCLUDED. For jobs that make use of
+# the BLOCK_JOB_READY event, job-cancel, block-job-cancel or
+# job-complete will still need to be used as appropriate.
#
# @id: The job identifier.
#
diff --git a/qapi/job.json b/qapi/job.json
index 9ddba537db..441cd7772b 100644
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -223,9 +223,9 @@
# jobs.
#
# This command will refuse to operate on any job that has not yet
-# reached its terminal state, JOB_STATUS_CONCLUDED. For jobs that
-# make use of JOB_READY event, job-cancel or job-complete will still
-# need to be used as appropriate.
+# reached its terminal state, CONCLUDED. For jobs that make use of
+# the JOB_READY event, job-cancel or job-complete will still need to
+# be used as appropriate.
#
# @id: The job identifier.
#
--
2.48.1
^ permalink raw reply related [flat|nested] 16+ messages in thread* [PATCH 13/13] qapi: Improve documentation around job state @concluded
2025-05-27 7:39 [PATCH 00/13] qapi: Doc fixes and improvements Markus Armbruster
` (11 preceding siblings ...)
2025-05-27 7:39 ` [PATCH 12/13] qapi: Tidy up references to job state CONCLUDED Markus Armbruster
@ 2025-05-27 7:39 ` Markus Armbruster
2025-05-27 12:51 ` [PATCH 00/13] qapi: Doc fixes and improvements Eric Blake
2025-06-03 6:39 ` Markus Armbruster
14 siblings, 0 replies; 16+ messages in thread
From: Markus Armbruster @ 2025-05-27 7:39 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, kwolf, jsnow, vsementsov, qemu-block
We use "the query list" in a few places. It's not entirely obvious
what that means. It's actually the output of query-jobs or
query-block-jobs.
Documentation of @auto-dismiss talks about the job disappearing from
the query list when it reaches state @concluded. This is less than
precise. The job doesn't merely disappear from the query list, it
disappears, period.
Documentation of JobStatus @concluded explains "the job will remain in
the query list until it is dismissed". Again less than precise. It
remains in state @concluded until dismissed.
Rephrase without use of "the query list" for clarity and precision.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/block-core.json | 19 +++++++------------
qapi/job.json | 2 +-
2 files changed, 8 insertions(+), 13 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index da390f85ac..1df6644f0d 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1417,8 +1417,8 @@
# @auto-finalize: Job will finalize itself when PENDING, moving to the
# CONCLUDED state. (since 2.12)
#
-# @auto-dismiss: Job will dismiss itself when CONCLUDED, moving to the
-# NULL state and disappearing from the query list. (since 2.12)
+# @auto-dismiss: Job will dismiss itself when CONCLUDED, and
+# disappear. (since 2.12)
#
# @error: Error information if the job did not complete successfully.
# Not set if the job completed successfully. (since 2.12.1)
@@ -1614,8 +1614,7 @@
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear
-# from the query list without user intervention. Defaults to
-# true. (Since 2.12)
+# without user intervention. Defaults to true. (Since 2.12)
#
# @filter-node-name: the node name that should be assigned to the
# filter driver that the backup job inserts into the graph above
@@ -1855,8 +1854,7 @@
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear
-# from the query list without user intervention. Defaults to
-# true. (Since 3.1)
+# without user intervention. Defaults to true. (Since 3.1)
#
# Features:
#
@@ -2219,8 +2217,7 @@
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear
-# from the query list without user intervention. Defaults to
-# true. (Since 3.1)
+# without user intervention. Defaults to true. (Since 3.1)
#
# Since: 1.3
##
@@ -2538,8 +2535,7 @@
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear
-# from the query list without user intervention. Defaults to
-# true. (Since 3.1)
+# without user intervention. Defaults to true. (Since 3.1)
#
# @target-is-zero: Assume the destination reads as all zeroes before
# the mirror started. Setting this to true can speed up the
@@ -2866,8 +2862,7 @@
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear
-# from the query list without user intervention. Defaults to
-# true. (Since 3.1)
+# without user intervention. Defaults to true. (Since 3.1)
#
# Errors:
# - If @device does not exist, DeviceNotFound.
diff --git a/qapi/job.json b/qapi/job.json
index 441cd7772b..126fa5ce60 100644
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -74,7 +74,7 @@
# process.
#
# @concluded: The job has finished all work. If auto-dismiss was set
-# to false, the job will remain in the query list until it is
+# to false, the job will remain in this state until it is
# dismissed via @job-dismiss.
#
# @null: The job is in the process of being dismantled. This state
--
2.48.1
^ permalink raw reply related [flat|nested] 16+ messages in thread* Re: [PATCH 00/13] qapi: Doc fixes and improvements
2025-05-27 7:39 [PATCH 00/13] qapi: Doc fixes and improvements Markus Armbruster
` (12 preceding siblings ...)
2025-05-27 7:39 ` [PATCH 13/13] qapi: Improve documentation around job state @concluded Markus Armbruster
@ 2025-05-27 12:51 ` Eric Blake
2025-06-03 6:39 ` Markus Armbruster
14 siblings, 0 replies; 16+ messages in thread
From: Eric Blake @ 2025-05-27 12:51 UTC (permalink / raw)
To: Markus Armbruster; +Cc: qemu-devel, kwolf, jsnow, vsementsov, qemu-block
On Tue, May 27, 2025 at 09:39:03AM +0200, Markus Armbruster wrote:
> Markus Armbruster (13):
> qapi: Tidy up run-together sentences in doc comments
> qapi: Tidy up whitespace in doc comments
> qapi: Move (since X.Y) to end of description
> qapi: Avoid breaking lines within (since X.Y)
> qapi: Drop a problematic (Since: 2.11) from query-hotpluggable-cpus
> qapi: Correct spelling of QEMU in doc comments
> qapi: Fix capitalization in doc comments
> qapi: Use proper markup instead of CAPS for emphasis in doc comments
> qapi: Spell JSON null correctly in blockdev-reopen documentation
> qapi: Refer to job-FOO instead of deprecated block-job-FOO in docs
> qapi: Mention both job-cancel and block-job-cancel in doc comments
> qapi: Tidy up references to job state CONCLUDED
> qapi: Improve documentation around job state @concluded
For the series:
Reviewed-by: Eric Blake <eblake@redhat.com>
--
Eric Blake, Principal Software Engineer
Red Hat, Inc.
Virtualization: qemu.org | libguestfs.org
^ permalink raw reply [flat|nested] 16+ messages in thread* Re: [PATCH 00/13] qapi: Doc fixes and improvements
2025-05-27 7:39 [PATCH 00/13] qapi: Doc fixes and improvements Markus Armbruster
` (13 preceding siblings ...)
2025-05-27 12:51 ` [PATCH 00/13] qapi: Doc fixes and improvements Eric Blake
@ 2025-06-03 6:39 ` Markus Armbruster
14 siblings, 0 replies; 16+ messages in thread
From: Markus Armbruster @ 2025-06-03 6:39 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, kwolf, jsnow, vsementsov, qemu-block
Queued.
^ permalink raw reply [flat|nested] 16+ messages in thread