[PULL 0/5] QAPI patches patches for 2023-07-26

[PULL 0/5] QAPI patches patches for 2023-07-26

[Markus Armbruster]

The following changes since commit 6cb2011fedf8c4e7b66b4a3abd6b42c1bae99ce6:

  Update version for v8.1.0-rc1 release (2023-07-25 20:09:05 +0100)

are available in the Git repository at:

  https://repo.or.cz/qemu/armbru.git tags/pull-qapi-2023-07-26

for you to fetch changes up to 1799bdcb47d8368c92cfc69c3b4f305ec8414977:

  qapi: Reformat recent doc comments to conform to current conventions (2023-07-26 13:26:53 +0200)

----------------------------------------------------------------
QAPI patches patches for 2023-07-26

----------------------------------------------------------------
The patches affect only documentation.  Generated code does not change.

Markus Armbruster (5):
      qapi/block-core: Tidy up BlockLatencyHistogramInfo documentation
      qapi/block: Tidy up block-latency-histogram-set documentation
      qapi/qdev: Tidy up device_add documentation
      qapi/trace: Tidy up trace-event-get-state, -set-state documentation
      qapi: Reformat recent doc comments to conform to current conventions

 qapi/block-core.json     | 85 +++++++++++++++++++++++-------------------------
 qapi/block.json          | 12 +++----
 qapi/cxl.json            |  4 +--
 qapi/machine-target.json |  2 +-
 qapi/migration.json      | 10 +++---
 qapi/net.json            |  1 -
 qapi/qdev.json           |  6 ++--
 qapi/qom.json            |  9 ++---
 qapi/trace.json          |  9 ++---
 qapi/ui.json             |  2 +-
 10 files changed, 66 insertions(+), 74 deletions(-)

-- 
2.41.0

[PULL 1/5] qapi/block-core: Tidy up BlockLatencyHistogramInfo documentation

[Markus Armbruster]

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>
Message-ID: <20230720071610.1096458-2-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

Re: [PULL 1/5] qapi/block-core: Tidy up BlockLatencyHistogramInfo documentation

[Vladimir Sementsov-Ogievskiy]

On 26.07.23 14:28, Markus Armbruster wrote:
> 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,

not same, but one more. N points break the line into N+1 intervals

>      "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>
> Message-ID: <20230720071610.1096458-2-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:
>   #
>   # ::
>   #

-- 
Best regards,
Vladimir

Re: [PULL 1/5] qapi/block-core: Tidy up BlockLatencyHistogramInfo documentation

[Markus Armbruster]

Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> writes:

> On 26.07.23 14:28, Markus Armbruster wrote:
>> 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,
>
> not same, but one more. N points break the line into N+1 intervals

Thanks for catching this.

What about "one more element than @boundaries has"?

>>      "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>
>> Message-ID: <20230720071610.1096458-2-armbru@redhat.com>

Re: [PULL 1/5] qapi/block-core: Tidy up BlockLatencyHistogramInfo documentation

[Vladimir Sementsov-Ogievskiy]

On 26.07.23 15:01, Markus Armbruster wrote:
> Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> writes:
> 
>> On 26.07.23 14:28, Markus Armbruster wrote:
>>> 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,
>>
>> not same, but one more. N points break the line into N+1 intervals
> 
> Thanks for catching this.
> 
> What about "one more element than @boundaries has"?

Sounds good!

> 
>>>       "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>
>>> Message-ID: <20230720071610.1096458-2-armbru@redhat.com>
> 

-- 
Best regards,
Vladimir

[PULL 2/5] qapi/block: Tidy up block-latency-histogram-set documentation

[Markus Armbruster]

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>
Message-ID: <20230720071610.1096458-3-armbru@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
---
 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

[PULL 3/5] qapi/qdev: Tidy up device_add documentation

[Markus Armbruster]

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>
Message-ID: <20230720071610.1096458-4-armbru@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org>
---
 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

[PULL 4/5] qapi/trace: Tidy up trace-event-get-state, -set-state documentation

[Markus Armbruster]

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>
Message-ID: <20230720071610.1096458-5-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

[PULL 5/5] qapi: Reformat recent doc comments to conform to current conventions

[Markus Armbruster]

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>
Message-ID: <20230720071610.1096458-7-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 2a6565a0f8..476b90bd50 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