qapi: Reformat recent doc comments to conform to current conventions

Since commit a937b6aa73 (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

@@ -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
+# @min_zone_append_latency_ns: Minimum latency of zone append
-#                              in the defined interval, in nanoseconds
+#     operations in the defined interval, in nanoseconds (since 8.1)
-#                              (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
+# @max_zone_append_latency_ns: Maximum latency of zone append
-#                              in the defined interval, in nanoseconds
+#     operations in the defined interval, in nanoseconds (since 8.1)
-#                              (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
+# @avg_zone_append_latency_ns: Average latency of zone append
-#                              in the defined interval, in nanoseconds
+#     operations in the defined interval, in nanoseconds (since 8.1)
-#                              (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
+#     operations in the defined interval (since 8.1).
-#                               (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
+# @zone_append_bytes: The number of bytes appended by the zoned
-#                     (since 8.1)
+#     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
+# @zone_append_operations: The number of zone append operations
-#                          by the zoned devices (since 8.1)
+#     performed by the zoned devices (since 8.1)
 #
 # @flush_operations: The number of cache flush operations performed by
 #     the device (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
+# @zone_append_merged: Number of zone append requests that have been
-#                      into another request (since 8.1)
+#     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
+# @failed_zone_append_operations: The number of failed zone append
-#                                 operations performed by the zoned devices
+#     write operations performed by the zoned devices (since 8.1)
-#                                 (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
+# @invalid_zone_append_operations: The number of invalid zone append
-#                                  performed by the zoned device (since 8.1)
+#     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)
 #
@@ -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
+# @discard-no-unref: when enabled, discards from the guest will not
-#     cluster allocations to be relinquished. This prevents qcow2 fragmentation
+#     cause cluster allocations to be relinquished.  This prevents
-#     that would be caused by such discards. Besides potential
+#     qcow2 fragmentation that would be caused by such discards.
-#     performance degradation, such fragmentation can lead to increased
+#     Besides potential performance degradation, such fragmentation
-#     allocation of clusters past the end of the image file,
+#     can lead to increased allocation of clusters past the end of the
-#     resulting in image files whose file length can grow much larger
+#     image file, resulting in image files whose file length can grow
-#     than their guest disk size would suggest.
+#     much larger than their guest disk size would suggest.  If image
-#     If image file length is of concern (e.g. when storing qcow2
+#     file length is of concern (e.g. when storing qcow2 images
-#     images directly on block devices), you should consider enabling
+#     directly on block devices), you should consider enabling this
-#     this option. (since 8.1)
+#     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
+# @block-state-zero: Force use of payload blocks of type 'ZERO'.
-#     'ZERO'. Non-standard, but default.  Do not set to 'off' when
+#     Non-standard, but default.  Do not set to 'off' when using
-#     using 'qemu-img convert' with subformat=dynamic.
+#     'qemu-img convert' with subformat=dynamic.
 #
 # Since: 2.12
 ##

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
+# @boundaries-zap: list of interval boundary values for zone append
-#                  latency histogram.
+#     write latency histogram.
 #
 # @boundaries-flush: list of interval boundary values for flush
 #     latency histogram.

qapi/cxl.json

@@ -172,8 +172,8 @@
 #
 # @temperature: Device temperature in degrees Celsius.
 #
-# @dirty-shutdown-count: Number of times the device has been unable
+# @dirty-shutdown-count: Number of times the device has been unable to
-#     to determine whether data loss may have occurred.
+#     determine whether data loss may have occurred.
 #
 # @corrected-volatile-error-count: Total number of correctable errors
 #     in volatile memory.

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
+# @x-ignore-shared: If enabled, QEMU will not migrate shared memory
-#     accessible on the destination machine. (since 4.0)
+#     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.
+#     sent depends on the migrated devices that use this feature.  For
-#     For example, a device can use it to make sure some of its data
+#     example, a device can use it to make sure some of its data is
-#     is sent and loaded in the destination before doing switchover.
+#     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)

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' },

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
+# @offset: the offset into the target file that the region starts at.
-#     can use this option to back multiple regions with a single file. Must
+#     You can use this option to back multiple regions with a single
-#     be a multiple of the page size. (default: 0) (since 8.1)
+#     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.

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