* [PATCH 1/6] qapi/block-core: Tidy up BlockLatencyHistogramInfo documentation
2023-07-20 7:16 [PATCH 0/6] qapi: Tidy up doc comments Markus Armbruster
@ 2023-07-20 7:16 ` Markus Armbruster
2023-07-20 7:16 ` [PATCH 2/6] qapi/block: Tidy up block-latency-histogram-set documentation Markus Armbruster
` (4 subsequent siblings)
5 siblings, 0 replies; 11+ messages in thread
From: Markus Armbruster @ 2023-07-20 7:16 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, Vladimir Sementsov-Ogievskiy
Documentation for member @bin comes out like
list of io request counts corresponding to histogram intervals.
len("bins") = len("boundaries") + 1 For the example above, "bins"
may be something like [3, 1, 5, 2], and corresponding histogram
looks like:
Note how the equation and the sentence following it run together.
Replace the equation:
list of io request counts corresponding to histogram intervals,
same number of elements as "boundaries". For the example above,
"bins" may be something like [3, 1, 5, 2], and corresponding
histogram looks like:
Cc: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/block-core.json | 7 +++----
1 file changed, 3 insertions(+), 4 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 5dd5f7e4b0..6ca448b6e6 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -652,10 +652,9 @@
# 10), [10, 50), [50, 100), [100, +inf).
#
# @bins: list of io request counts corresponding to histogram
-# intervals.
-# len(@bins) = len(@boundaries) + 1
-# For the example above, @bins may be something like [3, 1, 5, 2],
-# and corresponding histogram looks like:
+# intervals, same number of elements as @boundaries. For the
+# example above, @bins may be something like [3, 1, 5, 2], and
+# corresponding histogram looks like:
#
# ::
#
--
2.41.0
^ permalink raw reply related [flat|nested] 11+ messages in thread* [PATCH 2/6] qapi/block: Tidy up block-latency-histogram-set documentation
2023-07-20 7:16 [PATCH 0/6] qapi: Tidy up doc comments Markus Armbruster
2023-07-20 7:16 ` [PATCH 1/6] qapi/block-core: Tidy up BlockLatencyHistogramInfo documentation Markus Armbruster
@ 2023-07-20 7:16 ` Markus Armbruster
2023-07-20 13:39 ` Philippe Mathieu-Daudé
2023-07-20 7:16 ` [PATCH 3/6] qapi/qdev: Tidy up device_add documentation Markus Armbruster
` (3 subsequent siblings)
5 siblings, 1 reply; 11+ messages in thread
From: Markus Armbruster @ 2023-07-20 7:16 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake
Examples come out like
Example
set new histograms for all io types with intervals [0, 10), [10,
50), [50, 100), [100, +inf):
The sentence "set new histograms ..." starts with a lower case letter.
Capitalize it. Same for the other examples.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/block.json | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/qapi/block.json b/qapi/block.json
index 0f25ce3961..535892fddc 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -547,7 +547,7 @@
#
# Example:
#
-# set new histograms for all io types with intervals [0, 10), [10,
+# Set new histograms for all io types with intervals [0, 10), [10,
# 50), [50, 100), [100, +inf):
#
# -> { "execute": "block-latency-histogram-set",
@@ -557,7 +557,7 @@
#
# Example:
#
-# set new histogram only for write, other histograms will remain not
+# Set new histogram only for write, other histograms will remain not
# changed (or not created):
#
# -> { "execute": "block-latency-histogram-set",
@@ -567,7 +567,7 @@
#
# Example:
#
-# set new histograms with the following intervals: read, flush: [0,
+# Set new histograms with the following intervals: read, flush: [0,
# 10), [10, 50), [50, 100), [100, +inf) write: [0, 1000), [1000,
# 5000), [5000, +inf)
#
@@ -579,7 +579,7 @@
#
# Example:
#
-# remove all latency histograms:
+# Remove all latency histograms:
#
# -> { "execute": "block-latency-histogram-set",
# "arguments": { "id": "drive0" } }
--
2.41.0
^ permalink raw reply related [flat|nested] 11+ messages in thread* Re: [PATCH 2/6] qapi/block: Tidy up block-latency-histogram-set documentation
2023-07-20 7:16 ` [PATCH 2/6] qapi/block: Tidy up block-latency-histogram-set documentation Markus Armbruster
@ 2023-07-20 13:39 ` Philippe Mathieu-Daudé
0 siblings, 0 replies; 11+ messages in thread
From: Philippe Mathieu-Daudé @ 2023-07-20 13:39 UTC (permalink / raw)
To: Markus Armbruster, qemu-devel; +Cc: eblake
On 20/7/23 09:16, Markus Armbruster wrote:
> Examples come out like
>
> Example
>
> set new histograms for all io types with intervals [0, 10), [10,
> 50), [50, 100), [100, +inf):
>
> The sentence "set new histograms ..." starts with a lower case letter.
> Capitalize it. Same for the other examples.
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
> qapi/block.json | 8 ++++----
> 1 file changed, 4 insertions(+), 4 deletions(-)
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
^ permalink raw reply [flat|nested] 11+ messages in thread
* [PATCH 3/6] qapi/qdev: Tidy up device_add documentation
2023-07-20 7:16 [PATCH 0/6] qapi: Tidy up doc comments Markus Armbruster
2023-07-20 7:16 ` [PATCH 1/6] qapi/block-core: Tidy up BlockLatencyHistogramInfo documentation Markus Armbruster
2023-07-20 7:16 ` [PATCH 2/6] qapi/block: Tidy up block-latency-histogram-set documentation Markus Armbruster
@ 2023-07-20 7:16 ` Markus Armbruster
2023-07-20 13:42 ` Philippe Mathieu-Daudé
2023-07-20 7:16 ` [PATCH 4/6] qapi/trace: Tidy up trace-event-get-state, -set-state documentation Markus Armbruster
` (2 subsequent siblings)
5 siblings, 1 reply; 11+ messages in thread
From: Markus Armbruster @ 2023-07-20 7:16 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake
The notes section comes out like this:
Notes
Additional arguments depend on the type.
1. For detailed information about this command, please refer to the
‘docs/qdev-device-use.txt’ file.
2. It’s possible to list device properties by running QEMU with the
“-device DEVICE,help” command-line argument, where DEVICE is the
device’s name
The first item isn't numbered. Fix that:
1. Additional arguments depend on the type.
2. For detailed information about this command, please refer to the
‘docs/qdev-device-use.txt’ file.
3. It’s possible to list device properties by running QEMU with the
“-device DEVICE,help” command-line argument, where DEVICE is the
device’s name
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/qdev.json | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/qapi/qdev.json b/qapi/qdev.json
index 2d73b27c2a..6bc5a733b8 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -53,12 +53,12 @@
#
# Notes:
#
-# Additional arguments depend on the type.
+# 1. Additional arguments depend on the type.
#
-# 1. For detailed information about this command, please refer to the
+# 2. For detailed information about this command, please refer to the
# 'docs/qdev-device-use.txt' file.
#
-# 2. It's possible to list device properties by running QEMU with the
+# 3. It's possible to list device properties by running QEMU with the
# "-device DEVICE,help" command-line argument, where DEVICE is the
# device's name
#
--
2.41.0
^ permalink raw reply related [flat|nested] 11+ messages in thread* Re: [PATCH 3/6] qapi/qdev: Tidy up device_add documentation
2023-07-20 7:16 ` [PATCH 3/6] qapi/qdev: Tidy up device_add documentation Markus Armbruster
@ 2023-07-20 13:42 ` Philippe Mathieu-Daudé
0 siblings, 0 replies; 11+ messages in thread
From: Philippe Mathieu-Daudé @ 2023-07-20 13:42 UTC (permalink / raw)
To: Markus Armbruster, qemu-devel; +Cc: eblake
On 20/7/23 09:16, Markus Armbruster wrote:
> The notes section comes out like this:
>
> Notes
>
> Additional arguments depend on the type.
>
> 1. For detailed information about this command, please refer to the
> ‘docs/qdev-device-use.txt’ file.
>
> 2. It’s possible to list device properties by running QEMU with the
> “-device DEVICE,help” command-line argument, where DEVICE is the
> device’s name
>
> The first item isn't numbered. Fix that:
>
> 1. Additional arguments depend on the type.
>
> 2. For detailed information about this command, please refer to the
> ‘docs/qdev-device-use.txt’ file.
>
> 3. It’s possible to list device properties by running QEMU with the
> “-device DEVICE,help” command-line argument, where DEVICE is the
> device’s name
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
> qapi/qdev.json | 6 +++---
> 1 file changed, 3 insertions(+), 3 deletions(-)
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
^ permalink raw reply [flat|nested] 11+ messages in thread
* [PATCH 4/6] qapi/trace: Tidy up trace-event-get-state, -set-state documentation
2023-07-20 7:16 [PATCH 0/6] qapi: Tidy up doc comments Markus Armbruster
` (2 preceding siblings ...)
2023-07-20 7:16 ` [PATCH 3/6] qapi/qdev: Tidy up device_add documentation Markus Armbruster
@ 2023-07-20 7:16 ` Markus Armbruster
2023-07-20 7:16 ` [PATCH 5/6] qapi: Correct "eg." to "e.g." in documentation Markus Armbruster
2023-07-20 7:16 ` [PATCH 6/6] qapi: Reformat recent doc comments to conform to current conventions Markus Armbruster
5 siblings, 0 replies; 11+ messages in thread
From: Markus Armbruster @ 2023-07-20 7:16 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, Alex Bennée
trace-event-set-state's explanation of how events are selected is
under "Features". Doesn't belong there. Simply delete it, as it
feels redundant with documentation of member @name.
trace-event-get-state's explanation is under "Returns". Tolerable,
but similarly redundant. Delete it, too.
Cc: Alex Bennée <alex.bennee@linaro.org>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/trace.json | 7 +------
1 file changed, 1 insertion(+), 6 deletions(-)
diff --git a/qapi/trace.json b/qapi/trace.json
index 39b752fc88..0819d93016 100644
--- a/qapi/trace.json
+++ b/qapi/trace.json
@@ -60,9 +60,6 @@
#
# Returns: a list of @TraceEventInfo for the matching events
#
-# An event is returned if its name matches the @name pattern
-# (There are no longer any per-vCPU events).
-#
# Since: 2.2
#
# Example:
@@ -90,10 +87,8 @@
# @vcpu: The vCPU to act upon (all by default; since 2.7).
#
# Features:
-# @deprecated: Member @vcpu is deprecated, and always ignored.
#
-# An event is enabled if its name matches the @name pattern
-# (There are no longer any per-vCPU events).
+# @deprecated: Member @vcpu is deprecated, and always ignored.
#
# Since: 2.2
#
--
2.41.0
^ permalink raw reply related [flat|nested] 11+ messages in thread* [PATCH 5/6] qapi: Correct "eg." to "e.g." in documentation
2023-07-20 7:16 [PATCH 0/6] qapi: Tidy up doc comments Markus Armbruster
` (3 preceding siblings ...)
2023-07-20 7:16 ` [PATCH 4/6] qapi/trace: Tidy up trace-event-get-state, -set-state documentation Markus Armbruster
@ 2023-07-20 7:16 ` Markus Armbruster
2023-07-20 13:41 ` Philippe Mathieu-Daudé
2023-07-20 7:16 ` [PATCH 6/6] qapi: Reformat recent doc comments to conform to current conventions Markus Armbruster
5 siblings, 1 reply; 11+ messages in thread
From: Markus Armbruster @ 2023-07-20 7:16 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/char.json | 2 +-
qapi/misc.json | 2 +-
2 files changed, 2 insertions(+), 2 deletions(-)
diff --git a/qapi/char.json b/qapi/char.json
index e413ac2b70..52aaff25eb 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -18,7 +18,7 @@
# @filename: the filename of the character device
#
# @frontend-open: shows whether the frontend device attached to this
-# backend (eg. with the chardev=... option) is in open or closed
+# backend (e.g. with the chardev=... option) is in open or closed
# state (since 2.1)
#
# Notes: @filename is encoded using the QEMU command line character
diff --git a/qapi/misc.json b/qapi/misc.json
index ff070ec828..cda2effa81 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -18,7 +18,7 @@
# fail and the FD will be closed.
#
# @protocol: protocol name. Valid names are "vnc", "spice",
-# "@dbus-display" or the name of a character device (eg. from
+# "@dbus-display" or the name of a character device (e.g. from
# -chardev id=XXXX)
#
# @fdname: file descriptor name previously passed via 'getfd' command
--
2.41.0
^ permalink raw reply related [flat|nested] 11+ messages in thread* Re: [PATCH 5/6] qapi: Correct "eg." to "e.g." in documentation
2023-07-20 7:16 ` [PATCH 5/6] qapi: Correct "eg." to "e.g." in documentation Markus Armbruster
@ 2023-07-20 13:41 ` Philippe Mathieu-Daudé
2023-07-20 15:13 ` Markus Armbruster
0 siblings, 1 reply; 11+ messages in thread
From: Philippe Mathieu-Daudé @ 2023-07-20 13:41 UTC (permalink / raw)
To: Markus Armbruster, qemu-devel; +Cc: eblake, QEMU Trivial
Hi Markus,
On 20/7/23 09:16, Markus Armbruster wrote:
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
> qapi/char.json | 2 +-
> qapi/misc.json | 2 +-
> 2 files changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/qapi/char.json b/qapi/char.json
> index e413ac2b70..52aaff25eb 100644
> --- a/qapi/char.json
> +++ b/qapi/char.json
> @@ -18,7 +18,7 @@
> # @filename: the filename of the character device
> #
> # @frontend-open: shows whether the frontend device attached to this
> -# backend (eg. with the chardev=... option) is in open or closed
> +# backend (e.g. with the chardev=... option) is in open or closed
> # state (since 2.1)
> #
> # Notes: @filename is encoded using the QEMU command line character
> diff --git a/qapi/misc.json b/qapi/misc.json
> index ff070ec828..cda2effa81 100644
> --- a/qapi/misc.json
> +++ b/qapi/misc.json
> @@ -18,7 +18,7 @@
> # fail and the FD will be closed.
> #
> # @protocol: protocol name. Valid names are "vnc", "spice",
> -# "@dbus-display" or the name of a character device (eg. from
> +# "@dbus-display" or the name of a character device (e.g. from
> # -chardev id=XXXX)
> #
> # @fdname: file descriptor name previously passed via 'getfd' command
$ git grep -wF 'eg.' | wc -l
45
Why not fix all the tree?
^ permalink raw reply [flat|nested] 11+ messages in thread* Re: [PATCH 5/6] qapi: Correct "eg." to "e.g." in documentation
2023-07-20 13:41 ` Philippe Mathieu-Daudé
@ 2023-07-20 15:13 ` Markus Armbruster
0 siblings, 0 replies; 11+ messages in thread
From: Markus Armbruster @ 2023-07-20 15:13 UTC (permalink / raw)
To: Philippe Mathieu-Daudé; +Cc: qemu-devel, eblake, QEMU Trivial
Philippe Mathieu-Daudé <philmd@linaro.org> writes:
> Hi Markus,
>
> On 20/7/23 09:16, Markus Armbruster wrote:
>> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>> ---
>> qapi/char.json | 2 +-
>> qapi/misc.json | 2 +-
>> 2 files changed, 2 insertions(+), 2 deletions(-)
>> diff --git a/qapi/char.json b/qapi/char.json
>> index e413ac2b70..52aaff25eb 100644
>> --- a/qapi/char.json
>> +++ b/qapi/char.json
>> @@ -18,7 +18,7 @@
>> # @filename: the filename of the character device
>> #
>> # @frontend-open: shows whether the frontend device attached to this
>> -# backend (eg. with the chardev=... option) is in open or closed
>> +# backend (e.g. with the chardev=... option) is in open or closed
>> # state (since 2.1)
>> #
>> # Notes: @filename is encoded using the QEMU command line character
>> diff --git a/qapi/misc.json b/qapi/misc.json
>> index ff070ec828..cda2effa81 100644
>> --- a/qapi/misc.json
>> +++ b/qapi/misc.json
>> @@ -18,7 +18,7 @@
>> # fail and the FD will be closed.
>> #
>> # @protocol: protocol name. Valid names are "vnc", "spice",
>> -# "@dbus-display" or the name of a character device (eg. from
>> +# "@dbus-display" or the name of a character device (e.g. from
>> # -chardev id=XXXX)
>> #
>> # @fdname: file descriptor name previously passed via 'getfd' command
>
> $ git grep -wF 'eg.' | wc -l
> 45
>
> Why not fix all the tree?
Because I have qapi/ myopia today?
^ permalink raw reply [flat|nested] 11+ messages in thread
* [PATCH 6/6] qapi: Reformat recent doc comments to conform to current conventions
2023-07-20 7:16 [PATCH 0/6] qapi: Tidy up doc comments Markus Armbruster
` (4 preceding siblings ...)
2023-07-20 7:16 ` [PATCH 5/6] qapi: Correct "eg." to "e.g." in documentation Markus Armbruster
@ 2023-07-20 7:16 ` Markus Armbruster
5 siblings, 0 replies; 11+ messages in thread
From: Markus Armbruster @ 2023-07-20 7:16 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake
Since commit a937b6aa739 (qapi: Reformat doc comments to conform to
current conventions), a number of comments not conforming to the
current formatting conventions were added. No problem, just sweep
the entire documentation once more.
To check the generated documentation does not change, I compared the
generated HTML before and after this commit with "wdiff -3". Finds no
differences. Comparing with diff is not useful, as the reflown
paragraphs are visible there.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/block-core.json | 78 +++++++++++++++++++---------------------
qapi/block.json | 4 +--
qapi/cxl.json | 4 +--
qapi/machine-target.json | 2 +-
qapi/migration.json | 10 +++---
qapi/net.json | 1 -
qapi/qom.json | 9 ++---
qapi/trace.json | 2 ++
qapi/ui.json | 2 +-
9 files changed, 55 insertions(+), 57 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 6ca448b6e6..31c4812b44 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -136,7 +136,7 @@
#
# @filename: Name of the extent file
#
-# @format: Extent type (e.g. FLAT or SPARSE)
+# @format: Extent type (e.g. FLAT or SPARSE)
#
# @virtual-size: Number of bytes covered by this extent
#
@@ -853,9 +853,8 @@
# @min_wr_latency_ns: Minimum latency of write operations in the
# defined interval, in nanoseconds.
#
-# @min_zone_append_latency_ns: Minimum latency of zone append operations
-# in the defined interval, in nanoseconds
-# (since 8.1)
+# @min_zone_append_latency_ns: Minimum latency of zone append
+# operations in the defined interval, in nanoseconds (since 8.1)
#
# @min_flush_latency_ns: Minimum latency of flush operations in the
# defined interval, in nanoseconds.
@@ -866,9 +865,8 @@
# @max_wr_latency_ns: Maximum latency of write operations in the
# defined interval, in nanoseconds.
#
-# @max_zone_append_latency_ns: Maximum latency of zone append operations
-# in the defined interval, in nanoseconds
-# (since 8.1)
+# @max_zone_append_latency_ns: Maximum latency of zone append
+# operations in the defined interval, in nanoseconds (since 8.1)
#
# @max_flush_latency_ns: Maximum latency of flush operations in the
# defined interval, in nanoseconds.
@@ -879,9 +877,8 @@
# @avg_wr_latency_ns: Average latency of write operations in the
# defined interval, in nanoseconds.
#
-# @avg_zone_append_latency_ns: Average latency of zone append operations
-# in the defined interval, in nanoseconds
-# (since 8.1)
+# @avg_zone_append_latency_ns: Average latency of zone append
+# operations in the defined interval, in nanoseconds (since 8.1)
#
# @avg_flush_latency_ns: Average latency of flush operations in the
# defined interval, in nanoseconds.
@@ -893,8 +890,7 @@
# the defined interval.
#
# @avg_zone_append_queue_depth: Average number of pending zone append
-# operations in the defined interval
-# (since 8.1).
+# operations in the defined interval (since 8.1).
#
# Since: 2.5
##
@@ -919,8 +915,8 @@
#
# @wr_bytes: The number of bytes written by the device.
#
-# @zone_append_bytes: The number of bytes appended by the zoned devices
-# (since 8.1)
+# @zone_append_bytes: The number of bytes appended by the zoned
+# devices (since 8.1)
#
# @unmap_bytes: The number of bytes unmapped by the device (Since 4.2)
#
@@ -930,8 +926,8 @@
# @wr_operations: The number of write operations performed by the
# device.
#
-# @zone_append_operations: The number of zone append operations performed
-# by the zoned devices (since 8.1)
+# @zone_append_operations: The number of zone append operations
+# performed by the zoned devices (since 8.1)
#
# @flush_operations: The number of cache flush operations performed by
# the device (since 0.15)
@@ -946,7 +942,7 @@
# 0.15).
#
# @zone_append_total_time_ns: Total time spent on zone append writes
-# in nanoseconds (since 8.1)
+# in nanoseconds (since 8.1)
#
# @flush_total_time_ns: Total time spent on cache flushes in
# nanoseconds (since 0.15).
@@ -965,8 +961,8 @@
# @wr_merged: Number of write requests that have been merged into
# another request (Since 2.3).
#
-# @zone_append_merged: Number of zone append requests that have been merged
-# into another request (since 8.1)
+# @zone_append_merged: Number of zone append requests that have been
+# merged into another request (since 8.1)
#
# @unmap_merged: Number of unmap requests that have been merged into
# another request (Since 4.2)
@@ -981,9 +977,8 @@
# @failed_wr_operations: The number of failed write operations
# performed by the device (Since 2.5)
#
-# @failed_zone_append_operations: The number of failed zone append write
-# operations performed by the zoned devices
-# (since 8.1)
+# @failed_zone_append_operations: The number of failed zone append
+# write operations performed by the zoned devices (since 8.1)
#
# @failed_flush_operations: The number of failed flush operations
# performed by the device (Since 2.5)
@@ -997,8 +992,8 @@
# @invalid_wr_operations: The number of invalid write operations
# performed by the device (Since 2.5)
#
-# @invalid_zone_append_operations: The number of invalid zone append operations
-# performed by the zoned device (since 8.1)
+# @invalid_zone_append_operations: The number of invalid zone append
+# operations performed by the zoned device (since 8.1)
#
# @invalid_flush_operations: The number of invalid flush operations
# performed by the device (Since 2.5)
@@ -1019,7 +1014,8 @@
#
# @wr_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0)
#
-# @zone_append_latency_histogram: @BlockLatencyHistogramInfo. (since 8.1)
+# @zone_append_latency_histogram: @BlockLatencyHistogramInfo.
+# (since 8.1)
#
# @flush_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0)
#
@@ -1126,7 +1122,7 @@
#
# @parent: This describes the file block device if it has one.
# Contains recursively the statistics of the underlying protocol
-# (e.g. the host file for a qcow2 image). If there is no
+# (e.g. the host file for a qcow2 image). If there is no
# underlying protocol, this field is omitted
#
# @backing: This describes the backing block device if it has one.
@@ -1486,7 +1482,7 @@
# @format: the format of the overlay image, default is 'qcow2'.
#
# @mode: whether and how QEMU should create a new image, default is
-# 'absolute-paths'.
+# 'absolute-paths'.
##
{ 'struct': 'BlockdevSnapshotSync',
'data': { '*device': 'str', '*node-name': 'str',
@@ -1550,7 +1546,7 @@
#
# @bitmap: The name of a dirty bitmap to use. Must be present if sync
# is "bitmap" or "incremental". Can be present if sync is "full"
-# or "top". Must not be present otherwise.
+# or "top". Must not be present otherwise.
# (Since 2.4 (drive-backup), 3.1 (blockdev-backup))
#
# @bitmap-mode: Specifies the type of data the bitmap should contain
@@ -3477,16 +3473,16 @@
# @pass-discard-other: whether discard requests for the data source
# should be issued on other occasions where a cluster gets freed
#
-# @discard-no-unref: when enabled, discards from the guest will not cause
-# cluster allocations to be relinquished. This prevents qcow2 fragmentation
-# that would be caused by such discards. Besides potential
-# performance degradation, such fragmentation can lead to increased
-# allocation of clusters past the end of the image file,
-# resulting in image files whose file length can grow much larger
-# than their guest disk size would suggest.
-# If image file length is of concern (e.g. when storing qcow2
-# images directly on block devices), you should consider enabling
-# this option. (since 8.1)
+# @discard-no-unref: when enabled, discards from the guest will not
+# cause cluster allocations to be relinquished. This prevents
+# qcow2 fragmentation that would be caused by such discards.
+# Besides potential performance degradation, such fragmentation
+# can lead to increased allocation of clusters past the end of the
+# image file, resulting in image files whose file length can grow
+# much larger than their guest disk size would suggest. If image
+# file length is of concern (e.g. when storing qcow2 images
+# directly on block devices), you should consider enabling this
+# option. (since 8.1)
#
# @overlap-check: which overlap checks to perform for writes to the
# image, defaults to 'cached' (since 2.2)
@@ -5240,9 +5236,9 @@
#
# @subformat: vhdx subformat (default: dynamic)
#
-# @block-state-zero: Force use of payload blocks of type
-# 'ZERO'. Non-standard, but default. Do not set to 'off' when
-# using 'qemu-img convert' with subformat=dynamic.
+# @block-state-zero: Force use of payload blocks of type 'ZERO'.
+# Non-standard, but default. Do not set to 'off' when using
+# 'qemu-img convert' with subformat=dynamic.
#
# Since: 2.12
##
diff --git a/qapi/block.json b/qapi/block.json
index 535892fddc..998008cfa8 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -534,8 +534,8 @@
# @boundaries-write: list of interval boundary values for write
# latency histogram.
#
-# @boundaries-zap: list of interval boundary values for zone append write
-# latency histogram.
+# @boundaries-zap: list of interval boundary values for zone append
+# write latency histogram.
#
# @boundaries-flush: list of interval boundary values for flush
# latency histogram.
diff --git a/qapi/cxl.json b/qapi/cxl.json
index d5b5293eb5..8cc4c72fa9 100644
--- a/qapi/cxl.json
+++ b/qapi/cxl.json
@@ -172,8 +172,8 @@
#
# @temperature: Device temperature in degrees Celsius.
#
-# @dirty-shutdown-count: Number of times the device has been unable
-# to determine whether data loss may have occurred.
+# @dirty-shutdown-count: Number of times the device has been unable to
+# determine whether data loss may have occurred.
#
# @corrected-volatile-error-count: Total number of correctable errors
# in volatile memory.
diff --git a/qapi/machine-target.json b/qapi/machine-target.json
index 3362f8dc3f..f0a6b72414 100644
--- a/qapi/machine-target.json
+++ b/qapi/machine-target.json
@@ -61,7 +61,7 @@
# @CpuModelCompareResult:
#
# An enumeration of CPU model comparison results. The result is
-# usually calculated using e.g. CPU features or CPU generations.
+# usually calculated using e.g. CPU features or CPU generations.
#
# @incompatible: If model A is incompatible to model B, model A is not
# guaranteed to run where model B runs and the other way around.
diff --git a/qapi/migration.json b/qapi/migration.json
index 47dfef0278..5fb4494e22 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -465,8 +465,8 @@
# block devices (and thus take locks) immediately at the end of
# migration. (since 3.0)
#
-# @x-ignore-shared: If enabled, QEMU will not migrate shared memory that is
-# accessible on the destination machine. (since 4.0)
+# @x-ignore-shared: If enabled, QEMU will not migrate shared memory
+# that is accessible on the destination machine. (since 4.0)
#
# @validate-uuid: Send the UUID of the source to allow the destination
# to ensure it is the same. (since 4.2)
@@ -490,9 +490,9 @@
# @switchover-ack: If enabled, migration will not stop the source VM
# and complete the migration until an ACK is received from the
# destination that it's OK to do so. Exactly when this ACK is
-# sent depends on the migrated devices that use this feature.
-# For example, a device can use it to make sure some of its data
-# is sent and loaded in the destination before doing switchover.
+# sent depends on the migrated devices that use this feature. For
+# example, a device can use it to make sure some of its data is
+# sent and loaded in the destination before doing switchover.
# This can reduce downtime if devices that support this capability
# are present. 'return-path' capability must be enabled to use
# it. (since 8.1)
diff --git a/qapi/net.json b/qapi/net.json
index db67501308..313c8a606e 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -663,7 +663,6 @@
# @type: Specify the driver used for interpreting remaining arguments.
#
# Since: 1.2
-#
##
{ 'union': 'Netdev',
'base': { 'id': 'str', 'type': 'NetClientDriver' },
diff --git a/qapi/qom.json b/qapi/qom.json
index 7f92ea43e8..fa3e88c8e6 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -647,9 +647,10 @@
# selects a default alignment (currently the page size).
# (default: 0)
#
-# @offset: the offset into the target file that the region starts at. You
-# can use this option to back multiple regions with a single file. Must
-# be a multiple of the page size. (default: 0) (since 8.1)
+# @offset: the offset into the target file that the region starts at.
+# You can use this option to back multiple regions with a single
+# file. Must be a multiple of the page size.
+# (default: 0) (since 8.1)
#
# @discard-data: if true, the file contents can be destroyed when QEMU
# exits, to avoid unnecessarily flushing data to the backing file.
@@ -662,7 +663,7 @@
#
# @pmem: specifies whether the backing file specified by @mem-path is
# in host persistent memory that can be accessed using the SNIA
-# NVM programming model (e.g. Intel NVDIMM).
+# NVM programming model (e.g. Intel NVDIMM).
#
# @readonly: if true, the backing file is opened read-only; if false,
# it is opened read-write. (default: false)
diff --git a/qapi/trace.json b/qapi/trace.json
index 0819d93016..2077d7e117 100644
--- a/qapi/trace.json
+++ b/qapi/trace.json
@@ -38,6 +38,7 @@
# @vcpu: Whether this is a per-vCPU event (since 2.7).
#
# Features:
+#
# @deprecated: Member @vcpu is deprecated, and always ignored.
#
# Since: 2.2
@@ -56,6 +57,7 @@
# @vcpu: The vCPU to query (since 2.7).
#
# Features:
+#
# @deprecated: Member @vcpu is deprecated, and always ignored.
#
# Returns: a list of @TraceEventInfo for the matching events
diff --git a/qapi/ui.json b/qapi/ui.json
index bb06fb6039..006616aa77 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -1309,7 +1309,7 @@
# defaults to "off". (Since 3.1)
#
# @show-tabs: Display the tab bar for switching between the various
-# graphical interfaces (e.g. VGA and virtual console character
+# graphical interfaces (e.g. VGA and virtual console character
# devices) by default. (Since 7.1)
#
# @show-menubar: Display the main window menubar. Defaults to "on".
--
2.41.0
^ permalink raw reply related [flat|nested] 11+ messages in thread