[PATCH 00/12] qapi: Fairly trivial documentation work

[PATCH 00/12] qapi: Fairly trivial documentation work

[Markus Armbruster]

Markus Armbruster (12):
  qapi: Drop stray Arguments: line from qmp_capabilities docs
  qapi: Expand a few awkward abbreviations in documentation
  qapi: Tidy up block-latency-histogram-set documentation some more
  qapi: Tidy up indentation of add_client's example
  qapi: Fix argument markup in drive-mirror documentation
  qapi: Fix typo in request-ebpf documentation
  qapi: Fix abbreviation punctuation in doc comments
  qapi: Start sentences with a capital letter, end them with a period
  qapi: Don't repeat member type in its documentation text
  qapi: Refill doc comments to conform to current conventions
  qapi: Correct documentation indentation and whitespace
  qga/qapi-schema: Refill doc comments to conform to current conventions

 qapi/block-core.json     |  46 +++++------
 qapi/block.json          |  14 ++--
 qapi/control.json        |   2 -
 qapi/crypto.json         |  12 +--
 qapi/cxl.json            |   4 +-
 qapi/dump.json           |  18 ++---
 qapi/ebpf.json           |  14 ++--
 qapi/machine-target.json |  22 +++---
 qapi/machine.json        |  18 ++---
 qapi/migration.json      | 162 +++++++++++++++++++--------------------
 qapi/misc.json           |   8 +-
 qapi/net.json            |  27 ++++---
 qapi/qom.json            |  38 ++++-----
 qapi/replay.json         |   4 +-
 qapi/run-state.json      |  19 ++---
 qapi/sockets.json        |   3 +-
 qapi/ui.json             |  16 ++--
 qapi/virtio.json         |  20 +++--
 qga/qapi-schema.json     |  29 ++++---
 19 files changed, 240 insertions(+), 236 deletions(-)

-- 
2.44.0

[PATCH 01/12] qapi: Drop stray Arguments: line from qmp_capabilities docs

[Markus Armbruster]

Reported-by: John Snow <jsnow@redhat.com>
Fixes: 119ebac1feb2 (qapi-schema: use generated marshaller for 'qmp_capabilities')
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/control.json | 2 --
 1 file changed, 2 deletions(-)

diff --git a/qapi/control.json b/qapi/control.json
index f404daef60..6bdbf077c2 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -11,8 +11,6 @@
 #
 # Enable QMP capabilities.
 #
-# Arguments:
-#
 # @enable: An optional list of QMPCapability values to enable.  The
 #     client must not enable any capability that is not mentioned in
 #     the QMP greeting message.  If the field is not provided, it
-- 
2.44.0

[PATCH 02/12] qapi: Expand a few awkward abbreviations in documentation

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/replay.json | 4 ++--
 qapi/virtio.json | 8 +++++---
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/qapi/replay.json b/qapi/replay.json
index 8626fb58f4..d3559f9c8f 100644
--- a/qapi/replay.json
+++ b/qapi/replay.json
@@ -105,8 +105,8 @@
 # replaying the execution.  The command automatically loads nearest
 # snapshot and replays the execution to find the desired instruction.
 # When there is no preceding snapshot or the execution is not
-# replayed, then the command fails.  icount for the reference may be
-# obtained with @query-replay command.
+# replayed, then the command fails.  Instruction count can be obtained
+# with the @query-replay command.
 #
 # @icount: target instruction count
 #
diff --git a/qapi/virtio.json b/qapi/virtio.json
index 95745fdfd7..b0cd41be72 100644
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -642,15 +642,17 @@
 #
 # @num: vhost_virtqueue num
 #
-# @desc-phys: vhost_virtqueue desc_phys (descriptor area phys. addr.)
+# @desc-phys: vhost_virtqueue desc_phys (descriptor area physical
+#     address)
 #
 # @desc-size: vhost_virtqueue desc_size
 #
-# @avail-phys: vhost_virtqueue avail_phys (driver area phys. addr.)
+# @avail-phys: vhost_virtqueue avail_phys (driver area physical
+#     address)
 #
 # @avail-size: vhost_virtqueue avail_size
 #
-# @used-phys: vhost_virtqueue used_phys (device area phys. addr.)
+# @used-phys: vhost_virtqueue used_phys (device area physical address)
 #
 # @used-size: vhost_virtqueue used_size
 #
-- 
2.44.0

[PATCH 03/12] qapi: Tidy up block-latency-histogram-set documentation some more

[Markus Armbruster]

Commit a937b6aa739 (qapi: Reformat doc comments to conform to current
conventions) reflowed some text that should have been left alone.
Revert that.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/block.json | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/qapi/block.json b/qapi/block.json
index 65d9804bdf..2410145cd3 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -545,8 +545,8 @@
 #
 # Example:
 #
-#     Set new histograms for all io types with intervals [0, 10), [10,
-#     50), [50, 100), [100, +inf):
+#     Set new histograms for all io types with intervals
+#     [0, 10), [10, 50), [50, 100), [100, +inf):
 #
 #     -> { "execute": "block-latency-histogram-set",
 #          "arguments": { "id": "drive0",
@@ -565,9 +565,9 @@
 #
 # Example:
 #
-#     Set new histograms with the following intervals:   read, flush: [0,
-#     10), [10, 50), [50, 100), [100, +inf)   write: [0, 1000), [1000,
-#     5000), [5000, +inf)
+#     Set new histograms with the following intervals:
+#       read, flush: [0, 10), [10, 50), [50, 100), [100, +inf)
+#       write: [0, 1000), [1000, 5000), [5000, +inf)
 #
 #     -> { "execute": "block-latency-histogram-set",
 #          "arguments": { "id": "drive0",
-- 
2.44.0

[PATCH 04/12] qapi: Tidy up indentation of add_client's example

[Markus Armbruster]

Commit d23055b8db8 (qapi: Require descriptions and tagged sections to
be indented) indented add_client's example too much.  Revert that.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/misc.json | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/qapi/misc.json b/qapi/misc.json
index 1b0c5dad88..ec30e5c570 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -32,9 +32,9 @@
 #
 # Example:
 #
-#         -> { "execute": "add_client", "arguments": { "protocol": "vnc",
-#                                                      "fdname": "myclient" } }
-#         <- { "return": {} }
+#     -> { "execute": "add_client", "arguments": { "protocol": "vnc",
+#                                                  "fdname": "myclient" } }
+#     <- { "return": {} }
 ##
 { 'command': 'add_client',
   'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
@@ -142,7 +142,7 @@
 #     option was passed on the command line.
 #
 #     In the "suspended" state, it will completely stop the VM and
-#     cause a transition to the "paused" state. (Since 9.0)
+#     cause a transition to the "paused" state.  (Since 9.0)
 #
 # Example:
 #
-- 
2.44.0

[PATCH 05/12] qapi: Fix argument markup in drive-mirror documentation

[Markus Armbruster]

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 1874f880a8..64668b080d 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -2117,7 +2117,7 @@
 # Start mirroring a block device's writes to a new destination.
 # target specifies the target of the new image.  If the file exists,
 # or if it is a device, it will be used as the new destination for
-# writes.  If it does not exist, a new file will be created.  format
+# writes.  If it does not exist, a new file will be created.  @format
 # specifies the format of the mirror image, default is to probe if
 # mode='existing', else the format of the source.
 #
-- 
2.44.0

[PATCH 06/12] qapi: Fix typo in request-ebpf documentation

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/ebpf.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

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

[PATCH 07/12] qapi: Fix abbreviation punctuation in doc comments

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/migration.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/qapi/migration.json b/qapi/migration.json
index aa1b39bce1..faeb7d1ca9 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -1762,7 +1762,7 @@
 #        default network.
 #
 #     5. For now, number of migration streams is restricted to one,
-#        i.e number of items in 'channels' list is just 1.
+#        i.e. number of items in 'channels' list is just 1.
 #
 #     6. The 'uri' and 'channels' arguments are mutually exclusive;
 #        exactly one of the two should be present.
@@ -1839,7 +1839,7 @@
 #     3. The uri format is the same as for -incoming
 #
 #     4. For now, number of migration streams is restricted to one,
-#        i.e number of items in 'channels' list is just 1.
+#        i.e. number of items in 'channels' list is just 1.
 #
 #     5. The 'uri' and 'channels' arguments are mutually exclusive;
 #        exactly one of the two should be present.
-- 
2.44.0

[PATCH 08/12] qapi: Start sentences with a capital letter, end them with a period

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/migration.json | 16 ++++++++--------
 qapi/ui.json        |  2 +-
 2 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/qapi/migration.json b/qapi/migration.json
index faeb7d1ca9..9ce0f6249f 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -826,8 +826,8 @@
 #     and recreated on the fly while the migration server is active.
 #     If missing, it will default to denying access (Since 4.0)
 #
-# @max-bandwidth: to set maximum speed for migration.  maximum speed
-#     in bytes per second.  (Since 2.8)
+# @max-bandwidth: maximum speed for migration, in bytes per second.
+#     (Since 2.8)
 #
 # @avail-switchover-bandwidth: to set the available bandwidth that
 #     migration can use during switchover phase.  NOTE!  This does not
@@ -1023,8 +1023,8 @@
 #     control checking of the TLS x509 certificate distinguished name.
 #     (Since 4.0)
 #
-# @max-bandwidth: to set maximum speed for migration.  maximum speed
-#     in bytes per second.  (Since 2.8)
+# @max-bandwidth: maximum speed for migration, in bytes per second.
+#     (Since 2.8)
 #
 # @avail-switchover-bandwidth: to set the available bandwidth that
 #     migration can use during switchover phase.  NOTE!  This does not
@@ -1256,8 +1256,8 @@
 #     control checking of the TLS x509 certificate distinguished name.
 #     (Since 4.0)
 #
-# @max-bandwidth: to set maximum speed for migration.  maximum speed
-#     in bytes per second.  (Since 2.8)
+# @max-bandwidth: maximum speed for migration, in bytes per second.
+#     (Since 2.8)
 #
 # @avail-switchover-bandwidth: to set the available bandwidth that
 #     migration can use during switchover phase.  NOTE!  This does not
@@ -1949,8 +1949,8 @@
 #
 # @primary: true for primary or false for secondary.
 #
-# @failover: true to do failover, false to stop.  but cannot be
-#     specified if 'enable' is true.  default value is false.
+# @failover: true to do failover, false to stop.  Cannot be specified
+#     if 'enable' is true.  Default value is false.
 #
 # Example:
 #
diff --git a/qapi/ui.json b/qapi/ui.json
index 5744c24e3c..e71cd2f50b 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -290,7 +290,7 @@
 # @enabled: true if the SPICE server is enabled, false otherwise
 #
 # @migrated: true if the last guest migration completed and spice
-#     migration had completed as well.  false otherwise.  (since 1.4)
+#     migration had completed as well, false otherwise (since 1.4)
 #
 # @host: The hostname the SPICE server is bound to.  This depends on
 #     the name resolution on the host and may be an IP address.
-- 
2.44.0

[PATCH 09/12] qapi: Don't repeat member type in its documentation text

[Markus Armbruster]

Documentation generated for the arguments of MEMORY_FAILURE looks like

    "recipient": "MemoryFailureRecipient"
       recipient is defined as "MemoryFailureRecipient".

    "action": "MemoryFailureAction"
       action that has been taken.  action is defined as
       "MemoryFailureAction".

    "flags": "MemoryFailureFlags"
       flags for MemoryFailureAction.  action is defined as
       "MemoryFailureFlags".

The "action is defined as ..." are redundant.  Drop.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/run-state.json | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/qapi/run-state.json b/qapi/run-state.json
index 789fc34559..ae084e13a0 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -568,11 +568,9 @@
 #
 # @recipient: recipient is defined as @MemoryFailureRecipient.
 #
-# @action: action that has been taken.  action is defined as
-#     @MemoryFailureAction.
+# @action: action that has been taken.
 #
-# @flags: flags for MemoryFailureAction.  action is defined as
-#     @MemoryFailureFlags.
+# @flags: flags for MemoryFailureAction.
 #
 # Since: 5.2
 #
-- 
2.44.0

[PATCH 10/12] qapi: Refill doc comments to conform to current conventions

[Markus Armbruster]

For legibility, wrap text paragraphs so every line is at most 70
characters long.

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 refilled
paragraphs are visible there.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/block-core.json     |  24 ++++-----
 qapi/block.json          |   4 +-
 qapi/cxl.json            |   4 +-
 qapi/dump.json           |  16 +++---
 qapi/ebpf.json           |  12 ++---
 qapi/machine-target.json |  22 +++++----
 qapi/machine.json        |  15 +++---
 qapi/migration.json      | 104 ++++++++++++++++++++-------------------
 qapi/net.json            |  27 +++++-----
 qapi/qom.json            |  34 ++++++-------
 qapi/run-state.json      |   4 +-
 qapi/virtio.json         |  12 +++--
 12 files changed, 142 insertions(+), 136 deletions(-)

diff --git a/qapi/block-core.json b/qapi/block-core.json
index 64668b080d..e6b392ffe7 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1819,10 +1819,10 @@
 #     Care should be taken when specifying the string, to specify a
 #     valid filename or protocol.  (Since 2.1)
 #
-# @backing-mask-protocol: If true, replace any protocol mentioned in the
-#     'backing file format' with 'raw', rather than storing the protocol
-#     name as the backing format.  Can be used even when no image header
-#     will be updated (default false; since 9.0).
+# @backing-mask-protocol: If true, replace any protocol mentioned in
+#     the 'backing file format' with 'raw', rather than storing the
+#     protocol name as the backing format.  Can be used even when no
+#     image header will be updated (default false; since 9.0).
 #
 # @speed: the maximum speed, in bytes per second
 #
@@ -2825,10 +2825,10 @@
 #     Care should be taken when specifying the string, to specify a
 #     valid filename or protocol.  (Since 2.1)
 #
-# @backing-mask-protocol: If true, replace any protocol mentioned in the
-#     'backing file format' with 'raw', rather than storing the protocol
-#     name as the backing format.  Can be used even when no image header
-#     will be updated (default false; since 9.0).
+# @backing-mask-protocol: If true, replace any protocol mentioned in
+#     the 'backing file format' with 'raw', rather than storing the
+#     protocol name as the backing format.  Can be used even when no
+#     image header will be updated (default false; since 9.0).
 #
 # @speed: the maximum speed, in bytes per second
 #
@@ -3547,10 +3547,10 @@
 #     re-allocating them later.  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)
+#     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)
diff --git a/qapi/block.json b/qapi/block.json
index 2410145cd3..5de99fe09d 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -555,8 +555,8 @@
 #
 # Example:
 #
-#     Set new histogram only for write, other histograms will remain not
-#     changed (or not created):
+#     Set new histogram only for write, other histograms will remain
+#     not changed (or not created):
 #
 #     -> { "execute": "block-latency-histogram-set",
 #          "arguments": { "id": "drive0",
diff --git a/qapi/cxl.json b/qapi/cxl.json
index 8cc4c72fa9..4281726dec 100644
--- a/qapi/cxl.json
+++ b/qapi/cxl.json
@@ -144,8 +144,8 @@
 # @cxl-inject-memory-module-event:
 #
 # Inject an event record for a Memory Module Event (CXL r3.0
-# 8.2.9.2.1.3).  This event includes a copy of the Device Health
-# info at the time of the event.
+# 8.2.9.2.1.3).  This event includes a copy of the Device Health info
+# at the time of the event.
 #
 # @path: CXL type 3 device canonical QOM path
 #
diff --git a/qapi/dump.json b/qapi/dump.json
index 4c021dd53c..ef1f3b62fc 100644
--- a/qapi/dump.json
+++ b/qapi/dump.json
@@ -15,20 +15,20 @@
 #
 # @elf: elf format
 #
-# @kdump-zlib: makedumpfile flattened, kdump-compressed format with zlib
-#     compression
+# @kdump-zlib: makedumpfile flattened, kdump-compressed format with
+#     zlib compression
 #
 # @kdump-lzo: makedumpfile flattened, kdump-compressed format with lzo
 #     compression
 #
-# @kdump-snappy: makedumpfile flattened, kdump-compressed format with snappy
-#     compression
+# @kdump-snappy: makedumpfile flattened, kdump-compressed format with
+#     snappy compression
 #
-# @kdump-raw-zlib: raw assembled kdump-compressed format with zlib compression
-#     (since 8.2)
+# @kdump-raw-zlib: raw assembled kdump-compressed format with zlib
+#     compression (since 8.2)
 #
-# @kdump-raw-lzo: raw assembled kdump-compressed format with lzo compression
-#     (since 8.2)
+# @kdump-raw-lzo: raw assembled kdump-compressed format with lzo
+#     compression (since 8.2)
 #
 # @kdump-raw-snappy: raw assembled kdump-compressed format with snappy
 #     compression (since 8.2)
diff --git a/qapi/ebpf.json b/qapi/ebpf.json
index 61359e1c0f..e500b5a744 100644
--- a/qapi/ebpf.json
+++ b/qapi/ebpf.json
@@ -7,15 +7,13 @@
 ##
 # = eBPF Objects
 #
-# eBPF object is an ELF binary that contains the eBPF
-# program and eBPF map description(BTF). Overall, eBPF
-# object should contain the program and enough metadata
-# to create/load eBPF with libbpf. As the eBPF maps/program
-# should correspond to QEMU, the eBPF can't be used from
-# different QEMU build.
+# eBPF object is an ELF binary that contains the eBPF program and eBPF
+# map description(BTF). Overall, eBPF object should contain the
+# program and enough metadata to create/load eBPF with libbpf.  As the
+# eBPF maps/program should correspond to QEMU, the eBPF can't be used
+# from different QEMU build.
 #
 # Currently, there is a possible eBPF for receive-side scaling (RSS).
-#
 ##
 
 ##
diff --git a/qapi/machine-target.json b/qapi/machine-target.json
index 519adf3220..03d7a185b9 100644
--- a/qapi/machine-target.json
+++ b/qapi/machine-target.json
@@ -394,9 +394,9 @@
 ##
 # @set-cpu-topology:
 #
-# Modify the topology by moving the CPU inside the topology tree,
-# or by changing a modifier attribute of a CPU.
-# Absent values will not be modified.
+# Modify the topology by moving the CPU inside the topology tree, or
+# by changing a modifier attribute of a CPU.  Absent values will not
+# be modified.
 #
 # @core-id: the vCPU ID to be moved
 #
@@ -408,7 +408,8 @@
 #
 # @entitlement: entitlement to set
 #
-# @dedicated: whether the provisioning of real to virtual CPU is dedicated
+# @dedicated: whether the provisioning of real to virtual CPU is
+#     dedicated
 #
 # Features:
 #
@@ -435,14 +436,15 @@
 # Emitted when the guest asks to change the polarization.
 #
 # The guest can tell the host (via the PTF instruction) whether the
-# CPUs should be provisioned using horizontal or vertical polarization.
+# CPUs should be provisioned using horizontal or vertical
+# polarization.
 #
-# On horizontal polarization the host is expected to provision all vCPUs
-# equally.
+# On horizontal polarization the host is expected to provision all
+# vCPUs equally.
 #
-# On vertical polarization the host can provision each vCPU differently.
-# The guest will get information on the details of the provisioning
-# the next time it uses the STSI(15) instruction.
+# On vertical polarization the host can provision each vCPU
+# differently.  The guest will get information on the details of the
+# provisioning the next time it uses the STSI(15) instruction.
 #
 # @polarization: polarization specified by the guest
 #
diff --git a/qapi/machine.json b/qapi/machine.json
index 0840c91e70..01be411fa7 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -925,8 +925,7 @@
 # @cluster-id: cluster number within the parent container the CPU
 #     belongs to (since 7.1)
 #
-# @core-id: core number within the parent container the CPU
-#     belongs to
+# @core-id: core number within the parent container the CPU belongs to
 #
 # @thread-id: thread number within the core the CPU  belongs to
 #
@@ -982,8 +981,8 @@
 #
 # Examples:
 #
-#     For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu
-#     POWER8:
+#     For pseries machine type started with -smp 2,cores=2,maxcpus=4
+#     -cpu POWER8:
 #
 #     -> { "execute": "query-hotpluggable-cpus" }
 #     <- {"return": [
@@ -1008,8 +1007,8 @@
 #          }
 #        ]}
 #
-#     For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu
-#     qemu (Since: 2.11):
+#     For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2
+#     -cpu qemu (Since: 2.11):
 #
 #     -> { "execute": "query-hotpluggable-cpus" }
 #     <- {"return": [
@@ -1152,8 +1151,8 @@
 ##
 # @query-hv-balloon-status-report:
 #
-# Returns the hv-balloon driver data contained in the last received "STATUS"
-# message from the guest.
+# Returns the hv-balloon driver data contained in the last received
+# "STATUS" message from the guest.
 #
 # Returns:
 #     @HvBalloonInfo
diff --git a/qapi/migration.json b/qapi/migration.json
index 9ce0f6249f..302855198d 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -23,8 +23,8 @@
 #
 # @duplicate: number of duplicate (zero) pages (since 1.2)
 #
-# @skipped: number of skipped zero pages. Always zero, only provided for
-#     compatibility (since 1.5)
+# @skipped: number of skipped zero pages.  Always zero, only provided
+#     for compatibility (since 1.5)
 #
 # @normal: number of normal pages (since 1.2)
 #
@@ -501,8 +501,8 @@
 #
 # @background-snapshot: If enabled, the migration stream will be a
 #     snapshot of the VM exactly at the point when the migration
-#     procedure starts.  The VM RAM is saved with running VM. (since
-#     6.0)
+#     procedure starts.  The VM RAM is saved with running VM.
+#     (since 6.0)
 #
 # @zero-copy-send: Controls behavior on sending memory pages on
 #     migration.  When true, enables a zero-copy mechanism for sending
@@ -640,9 +640,9 @@
 #
 # @normal: the original form of migration. (since 8.2)
 #
-# @cpr-reboot: The migrate command stops the VM and saves state to
-#     the URI.  After quitting QEMU, the user resumes by running
-#     QEMU -incoming.
+# @cpr-reboot: The migrate command stops the VM and saves state to the
+#     URI.  After quitting QEMU, the user resumes by running QEMU
+#     -incoming.
 #
 #     This mode allows the user to quit QEMU, optionally update and
 #     reboot the OS, and restart QEMU.  If the user reboots, the URI
@@ -652,8 +652,8 @@
 #     does not block the migration, but the user must not modify the
 #     contents of guest block devices between the quit and restart.
 #
-#     This mode supports VFIO devices provided the user first puts
-#     the guest in the suspended runstate, such as by issuing
+#     This mode supports VFIO devices provided the user first puts the
+#     guest in the suspended runstate, such as by issuing
 #     guest-suspend-ram to the QEMU guest agent.
 #
 #     Best performance is achieved when the memory backend is shared
@@ -678,11 +678,10 @@
 # @legacy: Perform zero page checking in main migration thread.
 #
 # @multifd: Perform zero page checking in multifd sender thread if
-#     multifd migration is enabled, else in the main migration
-#     thread as for @legacy.
+#     multifd migration is enabled, else in the main migration thread
+#     as for @legacy.
 #
 # Since: 9.0
-#
 ##
 { 'enum': 'ZeroPageDetection',
   'data': [ 'none', 'legacy', 'multifd' ] }
@@ -831,13 +830,14 @@
 #
 # @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 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 can make the switchover decision much
-#     more accurate.  (Since 8.2)
+#     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
+#     can make the switchover decision much more accurate.
+#     (Since 8.2)
 #
 # @downtime-limit: set maximum tolerated downtime for migration.
 #     maximum downtime in milliseconds (Since 2.8)
@@ -899,14 +899,14 @@
 #     to their node name otherwise.  (Since 5.2)
 #
 # @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty
-#     limit during live migration.  Should be in the range 1 to 1000ms.
-#     Defaults to 1000ms.  (Since 8.1)
+#     limit during live migration.  Should be in the range 1 to
+#     1000ms.  Defaults to 1000ms.  (Since 8.1)
 #
 # @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration.
 #     Defaults to 1.  (Since 8.1)
 #
-# @mode: Migration mode. See description in @MigMode. Default is 'normal'.
-#        (Since 8.2)
+# @mode: Migration mode.  See description in @MigMode.  Default is
+#     'normal'.  (Since 8.2)
 #
 # @zero-page-detection: Whether and how to detect zero pages.
 #     See description in @ZeroPageDetection.  Default is 'multifd'.
@@ -919,8 +919,8 @@
 #     @compress-threads, @decompress-threads and @compress-wait-thread
 #     are deprecated because @compression is deprecated.
 #
-# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period
-#     are experimental.
+# @unstable: Members @x-checkpoint-delay and
+#     @x-vcpu-dirty-limit-period are experimental.
 #
 # Since: 2.4
 ##
@@ -1028,13 +1028,14 @@
 #
 # @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 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 can make the switchover decision much
-#     more accurate.  (Since 8.2)
+#     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
+#     can make the switchover decision much more accurate.
+#     (Since 8.2)
 #
 # @downtime-limit: set maximum tolerated downtime for migration.
 #     maximum downtime in milliseconds (Since 2.8)
@@ -1096,14 +1097,14 @@
 #     to their node name otherwise.  (Since 5.2)
 #
 # @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty
-#     limit during live migration.  Should be in the range 1 to 1000ms.
-#     Defaults to 1000ms.  (Since 8.1)
+#     limit during live migration.  Should be in the range 1 to
+#     1000ms.  Defaults to 1000ms.  (Since 8.1)
 #
 # @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration.
 #     Defaults to 1.  (Since 8.1)
 #
-# @mode: Migration mode. See description in @MigMode. Default is 'normal'.
-#        (Since 8.2)
+# @mode: Migration mode.  See description in @MigMode.  Default is
+#     'normal'.  (Since 8.2)
 #
 # @zero-page-detection: Whether and how to detect zero pages.
 #     See description in @ZeroPageDetection.  Default is 'multifd'.
@@ -1116,8 +1117,8 @@
 #     @compress-threads, @decompress-threads and @compress-wait-thread
 #     are deprecated because @compression is deprecated.
 #
-# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period
-#     are experimental.
+# @unstable: Members @x-checkpoint-delay and
+#     @x-vcpu-dirty-limit-period are experimental.
 #
 # TODO: either fuse back into MigrationParameters, or make
 #     MigrationParameters members mandatory
@@ -1261,13 +1262,14 @@
 #
 # @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 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 can make the switchover decision much
-#     more accurate.  (Since 8.2)
+#     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
+#     can make the switchover decision much more accurate.
+#     (Since 8.2)
 #
 # @downtime-limit: set maximum tolerated downtime for migration.
 #     maximum downtime in milliseconds (Since 2.8)
@@ -1329,14 +1331,14 @@
 #     to their node name otherwise.  (Since 5.2)
 #
 # @x-vcpu-dirty-limit-period: Periodic time (in milliseconds) of dirty
-#     limit during live migration.  Should be in the range 1 to 1000ms.
-#     Defaults to 1000ms.  (Since 8.1)
+#     limit during live migration.  Should be in the range 1 to
+#     1000ms.  Defaults to 1000ms.  (Since 8.1)
 #
 # @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration.
 #     Defaults to 1.  (Since 8.1)
 #
-# @mode: Migration mode. See description in @MigMode. Default is 'normal'.
-#        (Since 8.2)
+# @mode: Migration mode.  See description in @MigMode.  Default is
+#        'normal'.  (Since 8.2)
 #
 # @zero-page-detection: Whether and how to detect zero pages.
 #     See description in @ZeroPageDetection.  Default is 'multifd'.
@@ -1349,8 +1351,8 @@
 #     @compress-threads, @decompress-threads and @compress-wait-thread
 #     are deprecated because @compression is deprecated.
 #
-# @unstable: Members @x-checkpoint-delay and @x-vcpu-dirty-limit-period
-#     are experimental.
+# @unstable: Members @x-checkpoint-delay and
+#     @x-vcpu-dirty-limit-period are experimental.
 #
 # Since: 2.4
 ##
diff --git a/qapi/net.json b/qapi/net.json
index 417b61a321..0f5a259475 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -425,8 +425,8 @@
 #
 # @skb: generic mode, no driver support necessary
 #
-# @native: DRV mode, program is attached to a driver, packets are passed to
-#     the socket without allocation of skb.
+# @native: DRV mode, program is attached to a driver, packets are
+#     passed to the socket without allocation of skb.
 #
 # Since: 8.2
 ##
@@ -441,23 +441,26 @@
 #
 # @ifname: The name of an existing network interface.
 #
-# @mode: Attach mode for a default XDP program.  If not specified, then
-#     'native' will be tried first, then 'skb'.
+# @mode: Attach mode for a default XDP program.  If not specified,
+#     then 'native' will be tried first, then 'skb'.
 #
 # @force-copy: Force XDP copy mode even if device supports zero-copy.
 #     (default: false)
 #
-# @queues: number of queues to be used for multiqueue interfaces (default: 1).
+# @queues: number of queues to be used for multiqueue interfaces
+#     (default: 1).
 #
-# @start-queue: Use @queues starting from this queue number (default: 0).
+# @start-queue: Use @queues starting from this queue number
+#     (default: 0).
 #
-# @inhibit: Don't load a default XDP program, use one already loaded to
-#     the interface (default: false).  Requires @sock-fds.
+# @inhibit: Don't load a default XDP program, use one already loaded
+#     to the interface (default: false).  Requires @sock-fds.
 #
-# @sock-fds: A colon (:) separated list of file descriptors for already open
-#     but not bound AF_XDP sockets in the queue order.  One fd per queue.
-#     These descriptors should already be added into XDP socket map for
-#     corresponding queues.  Requires @inhibit.
+# @sock-fds: A colon (:) separated list of file descriptors for
+#     already open but not bound AF_XDP sockets in the queue order.
+#     One fd per queue.  These descriptors should already be added
+#     into XDP socket map for corresponding queues.  Requires
+#     @inhibit.
 #
 # Since: 8.2
 ##
diff --git a/qapi/qom.json b/qapi/qom.json
index baae3a183f..e263e29a26 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -668,19 +668,20 @@
 # @readonly: if true, the backing file is opened read-only; if false,
 #     it is opened read-write.  (default: false)
 #
-# @rom: whether to create Read Only Memory (ROM) that cannot be modified
-#       by the VM.  Any write attempts to such ROM will be denied.  Most
-#       use cases want writable RAM instead of ROM.  However, selected use
-#       cases, like R/O NVDIMMs, can benefit from ROM.  If set to 'on',
-#       create ROM; if set to 'off', create writable RAM;  if set to
-#       'auto', the value of the @readonly property is used.  This
-#       property is primarily helpful when we want to have proper RAM in
-#       configurations that would traditionally create ROM before this
-#       property was introduced: VM templating, where we want to open a
-#       file readonly (@readonly set to true) and mark the memory to be
-#       private for QEMU (@share set to false).  For this use case, we need
-#       writable RAM instead of ROM, and want to set this property to 'off'.
-#       (default: auto, since 8.2)
+# @rom: whether to create Read Only Memory (ROM) that cannot be
+#     modified by the VM.  Any write attempts to such ROM will be
+#     denied.  Most use cases want writable RAM instead of ROM.
+#     However, selected use cases, like R/O NVDIMMs, can benefit from
+#     ROM.  If set to 'on', create ROM; if set to 'off', create
+#     writable RAM; if set to 'auto', the value of the @readonly
+#     property is used.  This property is primarily helpful when we
+#     want to have proper RAM in configurations that would
+#     traditionally create ROM before this property was introduced: VM
+#     templating, where we want to open a file readonly (@readonly set
+#     to true) and mark the memory to be private for QEMU (@share set
+#     to false).  For this use case, we need writable RAM instead of
+#     ROM, and want to set this property to 'off'.  (default: auto,
+#     since 8.2)
 #
 # Since: 2.1
 ##
@@ -801,10 +802,9 @@
 #
 # @fd: file descriptor name previously passed via 'getfd' command,
 #     which represents a pre-opened /dev/iommu.  This allows the
-#     iommufd object to be shared accross several subsystems
-#     (VFIO, VDPA, ...), and the file descriptor to be shared
-#     with other process, e.g. DPDK.  (default: QEMU opens
-#     /dev/iommu by itself)
+#     iommufd object to be shared accross several subsystems (VFIO,
+#     VDPA, ...), and the file descriptor to be shared with other
+#     process, e.g. DPDK.  (default: QEMU opens /dev/iommu by itself)
 #
 # Since: 9.0
 ##
diff --git a/qapi/run-state.json b/qapi/run-state.json
index ae084e13a0..bc1c3a9217 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -144,8 +144,8 @@
 #     hardware-specific action) rather than a host request (such as
 #     sending qemu a SIGINT). (since 2.10)
 #
-# @reason: The @ShutdownCause which resulted in the SHUTDOWN. (since
-#     4.0)
+# @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 follow the
diff --git a/qapi/virtio.json b/qapi/virtio.json
index b0cd41be72..74fc27c702 100644
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -938,10 +938,11 @@
 #
 # @iothread: the id of IOThread object
 #
-# @vqs: an optional array of virtqueue indices that will be handled by this
-#     IOThread.  When absent, virtqueues are assigned round-robin across all
-#     IOThreadVirtQueueMappings provided.  Either all IOThreadVirtQueueMappings
-#     must have @vqs or none of them must have it.
+# @vqs: an optional array of virtqueue indices that will be handled by
+#     this IOThread.  When absent, virtqueues are assigned round-robin
+#     across all IOThreadVirtQueueMappings provided.  Either all
+#     IOThreadVirtQueueMappings must have @vqs or none of them must
+#     have it.
 #
 # Since: 9.0
 ##
@@ -952,7 +953,8 @@
 ##
 # @DummyVirtioForceArrays:
 #
-# Not used by QMP; hack to let us use IOThreadVirtQueueMappingList internally
+# Not used by QMP; hack to let us use IOThreadVirtQueueMappingList
+# internally
 #
 # Since: 9.0
 ##
-- 
2.44.0

[PATCH 11/12] qapi: Correct documentation indentation and whitespace

[Markus Armbruster]

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/block-core.json | 20 ++++++++++----------
 qapi/crypto.json     | 12 ++++++------
 qapi/dump.json       |  2 +-
 qapi/machine.json    |  3 +--
 qapi/migration.json  | 38 ++++++++++++++++++--------------------
 qapi/qom.json        |  4 ++--
 qapi/run-state.json  |  9 ++++-----
 qapi/sockets.json    |  3 +--
 qapi/ui.json         | 14 +++++++-------
 9 files changed, 50 insertions(+), 55 deletions(-)

diff --git a/qapi/block-core.json b/qapi/block-core.json
index e6b392ffe7..7d3fe59f6c 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -2593,27 +2593,27 @@
 #
 # @bps_max_length: maximum length of the @bps_max burst period, in
 #     seconds.  It must only be set if @bps_max is set as well.
-#     Defaults to 1. (Since 2.6)
+#     Defaults to 1.  (Since 2.6)
 #
 # @bps_rd_max_length: maximum length of the @bps_rd_max burst period,
 #     in seconds.  It must only be set if @bps_rd_max is set as well.
-#     Defaults to 1. (Since 2.6)
+#     Defaults to 1.  (Since 2.6)
 #
 # @bps_wr_max_length: maximum length of the @bps_wr_max burst period,
 #     in seconds.  It must only be set if @bps_wr_max is set as well.
-#     Defaults to 1. (Since 2.6)
+#     Defaults to 1.  (Since 2.6)
 #
 # @iops_max_length: maximum length of the @iops burst period, in
 #     seconds.  It must only be set if @iops_max is set as well.
-#     Defaults to 1. (Since 2.6)
+#     Defaults to 1.  (Since 2.6)
 #
 # @iops_rd_max_length: maximum length of the @iops_rd_max burst
 #     period, in seconds.  It must only be set if @iops_rd_max is set
-#     as well.  Defaults to 1. (Since 2.6)
+#     as well.  Defaults to 1.  (Since 2.6)
 #
 # @iops_wr_max_length: maximum length of the @iops_wr_max burst
 #     period, in seconds.  It must only be set if @iops_wr_max is set
-#     as well.  Defaults to 1. (Since 2.6)
+#     as well.  Defaults to 1.  (Since 2.6)
 #
 # @iops_size: an I/O size in bytes (Since 1.7)
 #
@@ -3354,7 +3354,7 @@
 #     decryption key (since 2.6). Mandatory except when doing a
 #     metadata-only probe of the image.
 #
-# @header: block device holding a detached LUKS header. (since 9.0)
+# @header: block device holding a detached LUKS header.  (since 9.0)
 #
 # Since: 2.9
 ##
@@ -4619,7 +4619,7 @@
 #     seconds for copy-before-write operation.  When a timeout occurs,
 #     the respective copy-before-write operation will fail, and the
 #     @on-cbw-error parameter will decide how this failure is handled.
-#     Default 0. (Since 7.1)
+#     Default 0.  (Since 7.1)
 #
 # Since: 6.2
 ##
@@ -4953,9 +4953,9 @@
 # Driver specific image creation options for LUKS.
 #
 # @file: Node to create the image format on, mandatory except when
-#        'preallocation' is not requested
+#     'preallocation' is not requested
 #
-# @header: Block device holding a detached LUKS header. (since 9.0)
+# @header: Block device holding a detached LUKS header.  (since 9.0)
 #
 # @size: Size of the virtual disk in bytes
 #
diff --git a/qapi/crypto.json b/qapi/crypto.json
index 931c88e688..e102be337b 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -48,15 +48,15 @@
 #
 # @sha1: SHA-1. Should not be used in any new code, legacy compat only
 #
-# @sha224: SHA-224. (since 2.7)
+# @sha224: SHA-224.  (since 2.7)
 #
 # @sha256: SHA-256. Current recommended strong hash.
 #
-# @sha384: SHA-384. (since 2.7)
+# @sha384: SHA-384.  (since 2.7)
 #
-# @sha512: SHA-512. (since 2.7)
+# @sha512: SHA-512.  (since 2.7)
 #
-# @ripemd160: RIPEMD-160. (since 2.7)
+# @ripemd160: RIPEMD-160.  (since 2.7)
 #
 # Since: 2.6
 ##
@@ -224,9 +224,9 @@
 #     'sha256'
 #
 # @iter-time: number of milliseconds to spend in PBKDF passphrase
-#     processing.  Currently defaults to 2000. (since 2.8)
+#     processing.  Currently defaults to 2000.  (since 2.8)
 #
-# @detached-header: create a detached LUKS header. (since 9.0)
+# @detached-header: create a detached LUKS header.  (since 9.0)
 #
 # Since: 2.6
 ##
diff --git a/qapi/dump.json b/qapi/dump.json
index ef1f3b62fc..2fa9504d86 100644
--- a/qapi/dump.json
+++ b/qapi/dump.json
@@ -77,7 +77,7 @@
 #
 # @detach: if true, QMP will return immediately rather than waiting
 #     for the dump to finish.  The user can track progress using
-#     "query-dump". (since 2.6).
+#     "query-dump".  (since 2.6).
 #
 # @begin: if specified, the starting physical address.
 #
diff --git a/qapi/machine.json b/qapi/machine.json
index 01be411fa7..e8b60641f2 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -920,7 +920,7 @@
 # @socket-id: socket number within parent container the CPU belongs to
 #
 # @die-id: die number within the parent container the CPU belongs to
-#    (since 4.1)
+#     (since 4.1)
 #
 # @cluster-id: cluster number within the parent container the CPU
 #     belongs to (since 7.1)
@@ -1190,7 +1190,6 @@
 #     <- { "event": "HV_BALLOON_STATUS_REPORT",
 #          "data": { "committed": 816640000, "available": 3333054464 },
 #          "timestamp": { "seconds": 1600295492, "microseconds": 661044 } }
-#
 ##
 { 'event': 'HV_BALLOON_STATUS_REPORT',
   'data': 'HvBalloonInfo' }
diff --git a/qapi/migration.json b/qapi/migration.json
index 302855198d..992ca32357 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -68,7 +68,6 @@
 # @deprecated: Member @skipped is always zero since 1.5.3
 #
 # Since: 0.14
-#
 ##
 { 'struct': 'MigrationStats',
   'data': {'transferred': 'int', 'remaining': 'int', 'total': 'int' ,
@@ -230,7 +229,7 @@
 #     throttled during auto-converge.  This is only present when
 #     auto-converge has started throttling guest cpus.  (Since 2.7)
 #
-# @error-desc: the human readable error description string. Clients
+# @error-desc: the human readable error description string.  Clients
 #     should not attempt to parse the error strings.  (Since 2.7)
 #
 # @postcopy-blocktime: total time when all vCPU were blocked during
@@ -638,7 +637,7 @@
 ##
 # @MigMode:
 #
-# @normal: the original form of migration. (since 8.2)
+# @normal: the original form of migration.  (since 8.2)
 #
 # @cpr-reboot: The migrate command stops the VM and saves state to the
 #     URI.  After quitting QEMU, the user resumes by running QEMU
@@ -781,15 +780,15 @@
 #
 # @throttle-trigger-threshold: The ratio of bytes_dirty_period and
 #     bytes_xfer_period to trigger throttling.  It is expressed as
-#     percentage.  The default value is 50. (Since 5.0)
+#     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.  The
-#     default value is 20. (Since 2.7)
+#     default value is 20.  (Since 2.7)
 #
 # @cpu-throttle-increment: throttle percentage increase each time
 #     auto-converge detects that migration is not making progress.
-#     The default value is 10. (Since 2.7)
+#     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
@@ -874,13 +873,13 @@
 #     migration, the compression level is an integer between 0 and 9,
 #     where 0 means no compression, 1 means the best compression
 #     speed, and 9 means best compression ratio which will consume
-#     more CPU. Defaults to 1. (Since 5.0)
+#     more CPU. Defaults to 1.  (Since 5.0)
 #
 # @multifd-zstd-level: Set the compression level to be used in live
 #     migration, the compression level is an integer between 0 and 20,
 #     where 0 means no compression, 1 means the best compression
 #     speed, and 20 means best compression ratio which will consume
-#     more CPU. Defaults to 1. (Since 5.0)
+#     more CPU. Defaults to 1.  (Since 5.0)
 #
 # @block-bitmap-mapping: Maps block nodes and bitmaps on them to
 #     aliases for the purpose of dirty bitmap migration.  Such aliases
@@ -976,15 +975,15 @@
 #
 # @throttle-trigger-threshold: The ratio of bytes_dirty_period and
 #     bytes_xfer_period to trigger throttling.  It is expressed as
-#     percentage.  The default value is 50. (Since 5.0)
+#     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.  The
-#     default value is 20. (Since 2.7)
+#     default value is 20.  (Since 2.7)
 #
 # @cpu-throttle-increment: throttle percentage increase each time
 #     auto-converge detects that migration is not making progress.
-#     The default value is 10. (Since 2.7)
+#     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
@@ -1072,13 +1071,13 @@
 #     migration, the compression level is an integer between 0 and 9,
 #     where 0 means no compression, 1 means the best compression
 #     speed, and 9 means best compression ratio which will consume
-#     more CPU. Defaults to 1. (Since 5.0)
+#     more CPU. Defaults to 1.  (Since 5.0)
 #
 # @multifd-zstd-level: Set the compression level to be used in live
 #     migration, the compression level is an integer between 0 and 20,
 #     where 0 means no compression, 1 means the best compression
 #     speed, and 20 means best compression ratio which will consume
-#     more CPU. Defaults to 1. (Since 5.0)
+#     more CPU. Defaults to 1.  (Since 5.0)
 #
 # @block-bitmap-mapping: Maps block nodes and bitmaps on them to
 #     aliases for the purpose of dirty bitmap migration.  Such aliases
@@ -1212,7 +1211,7 @@
 #
 # @throttle-trigger-threshold: The ratio of bytes_dirty_period and
 #     bytes_xfer_period to trigger throttling.  It is expressed as
-#     percentage.  The default value is 50. (Since 5.0)
+#     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
@@ -1306,13 +1305,13 @@
 #     migration, the compression level is an integer between 0 and 9,
 #     where 0 means no compression, 1 means the best compression
 #     speed, and 9 means best compression ratio which will consume
-#     more CPU. Defaults to 1. (Since 5.0)
+#     more CPU. Defaults to 1.  (Since 5.0)
 #
 # @multifd-zstd-level: Set the compression level to be used in live
 #     migration, the compression level is an integer between 0 and 20,
 #     where 0 means no compression, 1 means the best compression
 #     speed, and 20 means best compression ratio which will consume
-#     more CPU. Defaults to 1. (Since 5.0)
+#     more CPU. Defaults to 1.  (Since 5.0)
 #
 # @block-bitmap-mapping: Maps block nodes and bitmaps on them to
 #     aliases for the purpose of dirty bitmap migration.  Such aliases
@@ -1739,7 +1738,7 @@
 # @detach: this argument exists only for compatibility reasons and is
 #     ignored by QEMU
 #
-# @resume: resume one paused migration, default "off". (since 3.0)
+# @resume: resume one paused migration, default "off".  (since 3.0)
 #
 # Features:
 #
@@ -2165,7 +2164,6 @@
 # @millisecond: value is in milliseconds
 #
 # Since: 8.2
-#
 ##
 { 'enum': 'TimeUnit',
   'data': ['second', 'millisecond'] }
@@ -2247,7 +2245,7 @@
 #     will not increase dirty page rate anymore.
 #
 # @calc-time-unit: time unit in which @calc-time is specified.
-#     By default it is seconds. (Since 8.2)
+#     By default it is seconds.  (Since 8.2)
 #
 # @sample-pages: number of sampled pages per each GiB of guest memory.
 #     Default value is 512.  For 4KiB guest pages this corresponds to
@@ -2284,7 +2282,7 @@
 # Query results of the most recent invocation of @calc-dirty-rate.
 #
 # @calc-time-unit: time unit in which to report calculation time.
-#     By default it is reported in seconds. (Since 8.2)
+#     By default it is reported in seconds.  (Since 8.2)
 #
 # Since: 5.2
 #
diff --git a/qapi/qom.json b/qapi/qom.json
index e263e29a26..8d4ca8ed92 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -649,14 +649,14 @@
 #
 # @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.
+#     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.
 #     Note that @discard-data is only an optimization, and QEMU might
 #     not discard file contents if it aborts unexpectedly or is
-#     terminated using SIGKILL. (default: false)
+#     terminated using SIGKILL.  (default: false)
 #
 # @mem-path: the path to either a shared memory or huge page
 #     filesystem mount
diff --git a/qapi/run-state.json b/qapi/run-state.json
index bc1c3a9217..5f07444b84 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -91,7 +91,7 @@
 #
 # @snapshot-load: A snapshot is being loaded by the record & replay
 #     subsystem.  This value is used only within QEMU.  It doesn't
-#     occur in QMP. (since 7.2)
+#     occur in QMP.  (since 7.2)
 ##
 { 'enum': 'ShutdownCause',
   # Beware, shutdown_caused_by_guest() depends on enumeration order
@@ -109,7 +109,6 @@
 # @status: the virtual machine @RunState
 #
 # Since: 0.14
-#
 ##
 { 'struct': 'StatusInfo',
   'data': {'running': 'bool',
@@ -142,7 +141,7 @@
 # @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)
@@ -184,9 +183,9 @@
 # @guest: If true, the reset was triggered by a guest request (such as
 #     a guest-initiated ACPI reboot request or other hardware-specific
 #     action) rather than a host request (such as the QMP command
-#     system_reset). (since 2.10)
+#     system_reset).  (since 2.10)
 #
-# @reason: The @ShutdownCause of the RESET. (since 4.0)
+# @reason: The @ShutdownCause of the RESET.  (since 4.0)
 #
 # Since: 0.12
 #
diff --git a/qapi/sockets.json b/qapi/sockets.json
index ef777928e7..aa97c89768 100644
--- a/qapi/sockets.json
+++ b/qapi/sockets.json
@@ -58,7 +58,7 @@
 # @keep-alive: enable keep-alive when connecting to this socket.  Not
 #     supported for passive sockets.  (Since 4.2)
 #
-# @mptcp: enable multi-path TCP. (Since 6.1)
+# @mptcp: enable multi-path TCP.  (Since 6.1)
 #
 # Since: 1.3
 ##
@@ -125,7 +125,6 @@
 #     Decimal file descriptors are permitted at startup or other
 #     contexts where no monitor context is active.
 #
-#
 # Since: 1.2
 ##
 { 'struct': 'FdSocketAddress',
diff --git a/qapi/ui.json b/qapi/ui.json
index e71cd2f50b..9721c1e5af 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -181,7 +181,7 @@
 # @head: head to use in case the device supports multiple heads.  If
 #     this parameter is missing, head #0 will be used.  Also note that
 #     the head can only be specified in conjunction with the device
-#     ID. (Since 2.12)
+#     ID.  (Since 2.12)
 #
 # @format: image format for screendump.  (default: ppm) (Since 7.1)
 #
@@ -303,7 +303,7 @@
 #
 # @auth: the current authentication type used by the server
 #
-#     - 'none'  if no authentication is being used
+#     - 'none' if no authentication is being used
 #     - 'spice' uses SASL or direct TLS authentication, depending on
 #       command line options
 #
@@ -1314,7 +1314,7 @@
 #     display device can notify the guest on window resizes
 #     (virtio-gpu) this will default to "on", assuming the guest will
 #     resize the display to match the window size then.  Otherwise it
-#     defaults to "off". (Since 3.1)
+#     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
@@ -1417,12 +1417,12 @@
 #     codes match their position on non-Mac keyboards and you can use
 #     Meta/Super and Alt where you expect them.  (default: off)
 #
-# @zoom-to-fit: Zoom guest display to fit into the host window. When
-#     turned off the host window will be resized instead. Defaults to
-#     "off". (Since 8.2)
+# @zoom-to-fit: Zoom guest display to fit into the host window.  When
+#     turned off the host window will be resized instead.  Defaults to
+#     "off".  (Since 8.2)
 #
 # @zoom-interpolation: Apply interpolation to smooth output when
-#     zoom-to-fit is enabled. Defaults to "off". (Since 9.0)
+#     zoom-to-fit is enabled. Defaults to "off".  (Since 9.0)
 #
 # Since: 7.0
 ##
-- 
2.44.0

[PATCH 12/12] qga/qapi-schema: Refill doc comments to conform to current conventions

[Markus Armbruster]

For legibility, wrap text paragraphs so every line is at most 70
characters long.

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 refilled
paragraphs are visible there.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qga/qapi-schema.json | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index 9554b566a7..d5af155007 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -1220,13 +1220,13 @@
 # @signal: signal number (linux) or unhandled exception code (windows)
 #     if the process was abnormally terminated.
 #
-# @out-data: base64-encoded stdout of the process. This field will only
-#     be populated after the process exits.
+# @out-data: base64-encoded stdout of the process.  This field will
+#     only be populated after the process exits.
 #
-# @err-data: base64-encoded stderr of the process. Note: @out-data and
-#     @err-data are present only if 'capture-output' was specified for
-#     'guest-exec'. This field will only be populated after the process
-#     exits.
+# @err-data: base64-encoded stderr of the process.  Note: @out-data
+#     and @err-data are present only if 'capture-output' was specified
+#     for 'guest-exec'.  This field will only be populated after the
+#     process exits.
 #
 # @out-truncated: true if stdout was not fully captured due to size
 #     limitation.
@@ -1273,12 +1273,16 @@
 # An enumeration of guest-exec capture modes.
 #
 # @none: do not capture any output
+#
 # @stdout: only capture stdout
+#
 # @stderr: only capture stderr
+#
 # @separated: capture both stdout and stderr, but separated into
-#             GuestExecStatus out-data and err-data, respectively
-# @merged: capture both stdout and stderr, but merge together
-#          into out-data. not effective on windows guests.
+#     GuestExecStatus out-data and err-data, respectively
+#
+# @merged: capture both stdout and stderr, but merge together into
+#     out-data.  Not effective on windows guests.
 #
 # Since: 8.0
 ##
@@ -1291,8 +1295,9 @@
 #
 # Controls what guest-exec output gets captures.
 #
-# @flag: captures both stdout and stderr if true. Equivalent
-#        to GuestExecCaptureOutputMode::all. (since 2.5)
+# @flag: captures both stdout and stderr if true.  Equivalent to
+#     GuestExecCaptureOutputMode::all.  (since 2.5)
+#
 # @mode: capture mode; preferred interface
 #
 # Since: 8.0
@@ -1315,7 +1320,7 @@
 # @input-data: data to be passed to process stdin (base64 encoded)
 #
 # @capture-output: bool flag to enable capture of stdout/stderr of
-#     running process.  defaults to false.
+#     running process.  Defaults to false.
 #
 # Returns: PID
 #
-- 
2.44.0

Re: [PATCH 01/12] qapi: Drop stray Arguments: line from qmp_capabilities docs

[John Snow]

[-- Attachment #1: Type: text/plain, Size: 864 bytes --]

On Fri, Mar 22, 2024, 10:09 AM Markus Armbruster <armbru@redhat.com> wrote:

> Reported-by: John Snow <jsnow@redhat.com>
> Fixes: 119ebac1feb2 (qapi-schema: use generated marshaller for
> 'qmp_capabilities')
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
>

Reviewed-by: John Snow <jsnow@redhat.com>

---
>  qapi/control.json | 2 --
>  1 file changed, 2 deletions(-)
>
> diff --git a/qapi/control.json b/qapi/control.json
> index f404daef60..6bdbf077c2 100644
> --- a/qapi/control.json
> +++ b/qapi/control.json
> @@ -11,8 +11,6 @@
>  #
>  # Enable QMP capabilities.
>  #
> -# Arguments:
> -#
>  # @enable: An optional list of QMPCapability values to enable.  The
>  #     client must not enable any capability that is not mentioned in
>  #     the QMP greeting message.  If the field is not provided, it
> --
> 2.44.0
>
>

[-- Attachment #2: Type: text/html, Size: 1639 bytes --]

Re: [PATCH 04/12] qapi: Tidy up indentation of add_client's example

[Markus Armbruster]

Markus Armbruster <armbru@redhat.com> writes:

> Commit d23055b8db8 (qapi: Require descriptions and tagged sections to
> be indented) indented add_client's example too much.  Revert that.
>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qapi/misc.json | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/qapi/misc.json b/qapi/misc.json
> index 1b0c5dad88..ec30e5c570 100644
> --- a/qapi/misc.json
> +++ b/qapi/misc.json
> @@ -32,9 +32,9 @@
>  #
>  # Example:
>  #
> -#         -> { "execute": "add_client", "arguments": { "protocol": "vnc",
> -#                                                      "fdname": "myclient" } }
> -#         <- { "return": {} }
> +#     -> { "execute": "add_client", "arguments": { "protocol": "vnc",
> +#                                                  "fdname": "myclient" } }
> +#     <- { "return": {} }
>  ##
>  { 'command': 'add_client',
>    'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
> @@ -142,7 +142,7 @@
>  #     option was passed on the command line.
>  #
>  #     In the "suspended" state, it will completely stop the VM and
> -#     cause a transition to the "paused" state. (Since 9.0)
> +#     cause a transition to the "paused" state.  (Since 9.0)
>  #
>  # Example:
>  #

This hunk belongs to PATCH 11.