* [PATCH 01/12] qapi: Drop stray Arguments: line from qmp_capabilities docs
2024-03-22 14:08 [PATCH 00/12] qapi: Fairly trivial documentation work Markus Armbruster
@ 2024-03-22 14:08 ` Markus Armbruster
2024-03-22 15:24 ` John Snow
2024-03-22 14:09 ` [PATCH 02/12] qapi: Expand a few awkward abbreviations in documentation Markus Armbruster
` (10 subsequent siblings)
11 siblings, 1 reply; 15+ messages in thread
From: Markus Armbruster @ 2024-03-22 14:08 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, michael.roth, kkostiuk, John Snow
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
^ permalink raw reply related [flat|nested] 15+ messages in thread* Re: [PATCH 01/12] qapi: Drop stray Arguments: line from qmp_capabilities docs
2024-03-22 14:08 ` [PATCH 01/12] qapi: Drop stray Arguments: line from qmp_capabilities docs Markus Armbruster
@ 2024-03-22 15:24 ` John Snow
0 siblings, 0 replies; 15+ messages in thread
From: John Snow @ 2024-03-22 15:24 UTC (permalink / raw)
To: Markus Armbruster
Cc: qemu-devel, Eric Blake, Michael Roth, Konstantin Kostiuk
[-- 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 --]
^ permalink raw reply [flat|nested] 15+ messages in thread
* [PATCH 02/12] qapi: Expand a few awkward abbreviations in documentation
2024-03-22 14:08 [PATCH 00/12] qapi: Fairly trivial documentation work Markus Armbruster
2024-03-22 14:08 ` [PATCH 01/12] qapi: Drop stray Arguments: line from qmp_capabilities docs Markus Armbruster
@ 2024-03-22 14:09 ` Markus Armbruster
2024-03-22 14:09 ` [PATCH 03/12] qapi: Tidy up block-latency-histogram-set documentation some more Markus Armbruster
` (9 subsequent siblings)
11 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-03-22 14:09 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, michael.roth, kkostiuk
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
^ permalink raw reply related [flat|nested] 15+ messages in thread* [PATCH 03/12] qapi: Tidy up block-latency-histogram-set documentation some more
2024-03-22 14:08 [PATCH 00/12] qapi: Fairly trivial documentation work Markus Armbruster
2024-03-22 14:08 ` [PATCH 01/12] qapi: Drop stray Arguments: line from qmp_capabilities docs Markus Armbruster
2024-03-22 14:09 ` [PATCH 02/12] qapi: Expand a few awkward abbreviations in documentation Markus Armbruster
@ 2024-03-22 14:09 ` Markus Armbruster
2024-03-22 14:09 ` [PATCH 04/12] qapi: Tidy up indentation of add_client's example Markus Armbruster
` (8 subsequent siblings)
11 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-03-22 14:09 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, michael.roth, kkostiuk
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
^ permalink raw reply related [flat|nested] 15+ messages in thread* [PATCH 04/12] qapi: Tidy up indentation of add_client's example
2024-03-22 14:08 [PATCH 00/12] qapi: Fairly trivial documentation work Markus Armbruster
` (2 preceding siblings ...)
2024-03-22 14:09 ` [PATCH 03/12] qapi: Tidy up block-latency-histogram-set documentation some more Markus Armbruster
@ 2024-03-22 14:09 ` Markus Armbruster
2024-03-25 5:49 ` Markus Armbruster
2024-03-22 14:09 ` [PATCH 05/12] qapi: Fix argument markup in drive-mirror documentation Markus Armbruster
` (7 subsequent siblings)
11 siblings, 1 reply; 15+ messages in thread
From: Markus Armbruster @ 2024-03-22 14:09 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, michael.roth, kkostiuk
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
^ permalink raw reply related [flat|nested] 15+ messages in thread* Re: [PATCH 04/12] qapi: Tidy up indentation of add_client's example
2024-03-22 14:09 ` [PATCH 04/12] qapi: Tidy up indentation of add_client's example Markus Armbruster
@ 2024-03-25 5:49 ` Markus Armbruster
0 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-03-25 5:49 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, michael.roth, kkostiuk
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.
^ permalink raw reply [flat|nested] 15+ messages in thread
* [PATCH 05/12] qapi: Fix argument markup in drive-mirror documentation
2024-03-22 14:08 [PATCH 00/12] qapi: Fairly trivial documentation work Markus Armbruster
` (3 preceding siblings ...)
2024-03-22 14:09 ` [PATCH 04/12] qapi: Tidy up indentation of add_client's example Markus Armbruster
@ 2024-03-22 14:09 ` Markus Armbruster
2024-03-22 14:09 ` [PATCH 06/12] qapi: Fix typo in request-ebpf documentation Markus Armbruster
` (6 subsequent siblings)
11 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-03-22 14:09 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, michael.roth, kkostiuk
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
^ permalink raw reply related [flat|nested] 15+ messages in thread* [PATCH 06/12] qapi: Fix typo in request-ebpf documentation
2024-03-22 14:08 [PATCH 00/12] qapi: Fairly trivial documentation work Markus Armbruster
` (4 preceding siblings ...)
2024-03-22 14:09 ` [PATCH 05/12] qapi: Fix argument markup in drive-mirror documentation Markus Armbruster
@ 2024-03-22 14:09 ` Markus Armbruster
2024-03-22 14:09 ` [PATCH 07/12] qapi: Fix abbreviation punctuation in doc comments Markus Armbruster
` (5 subsequent siblings)
11 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-03-22 14:09 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, michael.roth, kkostiuk
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
^ permalink raw reply related [flat|nested] 15+ messages in thread* [PATCH 07/12] qapi: Fix abbreviation punctuation in doc comments
2024-03-22 14:08 [PATCH 00/12] qapi: Fairly trivial documentation work Markus Armbruster
` (5 preceding siblings ...)
2024-03-22 14:09 ` [PATCH 06/12] qapi: Fix typo in request-ebpf documentation Markus Armbruster
@ 2024-03-22 14:09 ` Markus Armbruster
2024-03-22 14:09 ` [PATCH 08/12] qapi: Start sentences with a capital letter, end them with a period Markus Armbruster
` (4 subsequent siblings)
11 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-03-22 14:09 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, michael.roth, kkostiuk
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
^ permalink raw reply related [flat|nested] 15+ messages in thread* [PATCH 08/12] qapi: Start sentences with a capital letter, end them with a period
2024-03-22 14:08 [PATCH 00/12] qapi: Fairly trivial documentation work Markus Armbruster
` (6 preceding siblings ...)
2024-03-22 14:09 ` [PATCH 07/12] qapi: Fix abbreviation punctuation in doc comments Markus Armbruster
@ 2024-03-22 14:09 ` Markus Armbruster
2024-03-22 14:09 ` [PATCH 09/12] qapi: Don't repeat member type in its documentation text Markus Armbruster
` (3 subsequent siblings)
11 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-03-22 14:09 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, michael.roth, kkostiuk
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
^ permalink raw reply related [flat|nested] 15+ messages in thread* [PATCH 09/12] qapi: Don't repeat member type in its documentation text
2024-03-22 14:08 [PATCH 00/12] qapi: Fairly trivial documentation work Markus Armbruster
` (7 preceding siblings ...)
2024-03-22 14:09 ` [PATCH 08/12] qapi: Start sentences with a capital letter, end them with a period Markus Armbruster
@ 2024-03-22 14:09 ` Markus Armbruster
2024-03-22 14:09 ` [PATCH 10/12] qapi: Refill doc comments to conform to current conventions Markus Armbruster
` (2 subsequent siblings)
11 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-03-22 14:09 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, michael.roth, kkostiuk
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
^ permalink raw reply related [flat|nested] 15+ messages in thread* [PATCH 10/12] qapi: Refill doc comments to conform to current conventions
2024-03-22 14:08 [PATCH 00/12] qapi: Fairly trivial documentation work Markus Armbruster
` (8 preceding siblings ...)
2024-03-22 14:09 ` [PATCH 09/12] qapi: Don't repeat member type in its documentation text Markus Armbruster
@ 2024-03-22 14:09 ` Markus Armbruster
2024-03-22 14:09 ` [PATCH 11/12] qapi: Correct documentation indentation and whitespace Markus Armbruster
2024-03-22 14:09 ` [PATCH 12/12] qga/qapi-schema: Refill doc comments to conform to current conventions Markus Armbruster
11 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-03-22 14:09 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, michael.roth, kkostiuk
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
^ permalink raw reply related [flat|nested] 15+ messages in thread* [PATCH 11/12] qapi: Correct documentation indentation and whitespace
2024-03-22 14:08 [PATCH 00/12] qapi: Fairly trivial documentation work Markus Armbruster
` (9 preceding siblings ...)
2024-03-22 14:09 ` [PATCH 10/12] qapi: Refill doc comments to conform to current conventions Markus Armbruster
@ 2024-03-22 14:09 ` Markus Armbruster
2024-03-22 14:09 ` [PATCH 12/12] qga/qapi-schema: Refill doc comments to conform to current conventions Markus Armbruster
11 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-03-22 14:09 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, michael.roth, kkostiuk
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
^ permalink raw reply related [flat|nested] 15+ messages in thread* [PATCH 12/12] qga/qapi-schema: Refill doc comments to conform to current conventions
2024-03-22 14:08 [PATCH 00/12] qapi: Fairly trivial documentation work Markus Armbruster
` (10 preceding siblings ...)
2024-03-22 14:09 ` [PATCH 11/12] qapi: Correct documentation indentation and whitespace Markus Armbruster
@ 2024-03-22 14:09 ` Markus Armbruster
11 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-03-22 14:09 UTC (permalink / raw)
To: qemu-devel; +Cc: eblake, michael.roth, kkostiuk
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
^ permalink raw reply related [flat|nested] 15+ messages in thread