From: Markus Armbruster Date: Mon, 3 Nov 2025 08:23:49 +0000 (+0100) Subject: qga/qapi-schema: Refill doc comments to conform to conventions X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e67b5099b434216044d9de30e2c09c3e210f1add;p=thirdparty%2Fqemu.git qga/qapi-schema: Refill doc comments to conform to conventions Sweep the entire documentation again. Last done in commit 7270819384c (qga/qapi-schema: Refill doc comments to conform to current conventions). To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the reflown paragraphs are visible there. Signed-off-by: Markus Armbruster Reviewed-by: Vladimir Sementsov-Ogievskiy Message-ID: <20251103082354.3273027-5-armbru@redhat.com> --- diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 8162d888bb..af75f12a28 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -2,8 +2,8 @@ # vim: filetype=python ## -# This manual describes the commands supported by the QEMU Guest -# Agent Protocol. +# This manual describes the commands supported by the QEMU Guest Agent +# Protocol. # # For locating a particular item, please see the `qapi-qga-index`. # @@ -96,8 +96,8 @@ # In cases where a partial stale response was previously received by # the client, this cannot always be done reliably. One particular # scenario being if qemu-ga responses are fed character-by-character -# into a JSON parser. In these situations, using `guest-sync-delimited` -# may be optimal. +# into a JSON parser. In these situations, using +# `guest-sync-delimited` may be optimal. # # For clients that fetch responses line by line and convert them to # JSON objects, `guest-sync` should be sufficient, but note that in @@ -153,9 +153,9 @@ # This command tries to set guest's System Time to the given value, # then sets the Hardware Clock (RTC) to the current System Time. This # will make it easier for a guest to resynchronize without waiting for -# NTP. If no @time is specified, then the time to set is read from -# RTC. However, this may not be supported on all platforms (i.e. -# Windows). If that's the case users are advised to always pass a +# NTP. If no @time is specified, then the time to set is read from +# RTC. However, this may not be supported on all platforms (i.e. +# Windows). If that's the case users are advised to always pass a # value. # # @time: time of nanoseconds, relative to the Epoch of 1970-01-01 in @@ -444,8 +444,8 @@ # Returns: Number of file systems currently frozen. # # .. note:: On Windows, the command is implemented with the help of a -# Volume Shadow-copy Service DLL helper. The frozen state is limited -# for up to 10 seconds by VSS. +# Volume Shadow-copy Service DLL helper. The frozen state is +# limited for up to 10 seconds by VSS. # # Since: 0.15.0 ## @@ -482,9 +482,9 @@ # Returns: Number of file systems thawed by this call # # .. note:: If the return value does not match the previous call to -# `guest-fsfreeze-freeze`, this likely means some freezable filesystems -# were unfrozen before this call, and that the filesystem state may -# have changed before issuing this command. +# `guest-fsfreeze-freeze`, this likely means some freezable +# filesystems were unfrozen before this call, and that the +# filesystem state may have changed before issuing this command. # # Since: 0.15.0 ## @@ -513,7 +513,8 @@ ## # @GuestFilesystemTrimResponse: # -# @paths: list of `GuestFilesystemTrimResult` per path that was trimmed +# @paths: list of `GuestFilesystemTrimResult` per path that was +# trimmed # # Since: 2.4 ## @@ -557,16 +558,16 @@ # # This command does NOT return a response on success. There is a high # chance the command succeeded if the VM exits with a zero exit status -# or, when running with --no-shutdown, by issuing the `query-status` QMP -# command to to confirm the VM status is "shutdown". However, the VM -# could also exit (or set its status to "shutdown") due to other +# or, when running with --no-shutdown, by issuing the `query-status` +# QMP command to to confirm the VM status is "shutdown". However, the +# VM could also exit (or set its status to "shutdown") due to other # reasons. # # Errors: # - If suspend to disk is not supported, Unsupported # -# .. note:: It's strongly recommended to issue the `guest-sync` command -# before sending commands when the guest resumes. +# .. note:: It's strongly recommended to issue the `guest-sync` +# command before sending commands when the guest resumes. # # Since: 1.1 ## @@ -586,7 +587,7 @@ # - manual write into sysfs # # IMPORTANT: `guest-suspend-ram` requires working wakeup support in -# QEMU. You should check QMP command `query-current-machine` returns +# QEMU. You should check QMP command `query-current-machine` returns # wakeup-suspend-support: true before issuing this command. Failure # in doing so can result in a suspended guest that QEMU will not be # able to awaken, forcing the user to power cycle the guest to bring @@ -602,8 +603,8 @@ # Errors: # - If suspend to ram is not supported, Unsupported # -# .. note:: It's strongly recommended to issue the `guest-sync` command -# before sending commands when the guest resumes. +# .. note:: It's strongly recommended to issue the `guest-sync` +# command before sending commands when the guest resumes. # # Since: 1.1 ## @@ -622,7 +623,7 @@ # - pm-utils (via pm-suspend-hybrid) # # IMPORTANT: `guest-suspend-hybrid` requires working wakeup support in -# QEMU. You should check QMP command `query-current-machine` returns +# QEMU. You should check QMP command `query-current-machine` returns # wakeup-suspend-support: true before issuing this command. Failure # in doing so can result in a suspended guest that QEMU will not be # able to awaken, forcing the user to power cycle the guest to bring @@ -638,8 +639,8 @@ # Errors: # - If hybrid suspend is not supported, Unsupported # -# .. note:: It's strongly recommended to issue the `guest-sync` command -# before sending commands when the guest resumes. +# .. note:: It's strongly recommended to issue the `guest-sync` +# command before sending commands when the guest resumes. # # Since: 1.1 ## @@ -1048,10 +1049,11 @@ # # @used-bytes: file system used bytes (since 3.0) # -# @total-bytes: filesystem capacity in bytes for unprivileged users (since 3.0) +# @total-bytes: filesystem capacity in bytes for unprivileged users +# (since 3.0) # -# @total-bytes-privileged: filesystem capacity in bytes for privileged users -# (since 9.1) +# @total-bytes-privileged: filesystem capacity in bytes for privileged +# users (since 9.1) # # @disk: an array of disk hardware information that the volume lies # on, which may be empty if the disk type is not supported @@ -1171,7 +1173,8 @@ ## # @GuestMemoryBlockResponse: # -# @phys-index: same with the 'phys-index' member of `GuestMemoryBlock`. +# @phys-index: same with the 'phys-index' member of +# `GuestMemoryBlock`. # # @response: the result of memory block operation. # @@ -1491,10 +1494,11 @@ # # .. note:: On POSIX systems the fields @id, @name, @pretty-name, # @version, @version-id, @variant and @variant-id follow the -# definition specified in os-release(5). Refer to the manual page for -# exact description of the fields. Their values are taken from the -# os-release file. If the file is not present in the system, or the -# values are not present in the file, the fields are not included. +# definition specified in os-release(5). Refer to the manual page +# for exact description of the fields. Their values are taken from +# the os-release file. If the file is not present in the system, +# or the values are not present in the file, the fields are not +# included. # # On Windows the values are filled from information gathered from # the system. @@ -1639,7 +1643,7 @@ # @guest-ssh-remove-authorized-keys: # # Remove public keys from the user .ssh/authorized_keys on Unix -# systems (not implemented for other systems). It's not an error if +# systems (not implemented for other systems). It's not an error if # the key is already missing. # # @username: the user account to remove the authorized keys @@ -1862,10 +1866,10 @@ # # Retrieve CPU process load information # -# .. note:: Windows does not have load average API, so QGA emulates it by -# calculating the average CPU usage in the last 1, 5, 15 minutes -# similar as Linux does this. -# Calculation starts from the first time this command is called. +# .. note:: Windows does not have load average API, so QGA emulates it +# by calculating the average CPU usage in the last 1, 5, 15 minutes +# similar as Linux does this. Calculation starts from the first +# time this command is called. # # Returns: load information # @@ -1881,9 +1885,11 @@ # # Route information, currently, only linux supported. # -# @iface: The destination network or host's egress network interface in the routing table +# @iface: The destination network or host's egress network interface +# in the routing table # -# @destination: The IP address of the target network or host, The final destination of the packet +# @destination: The IP address of the target network or host, The +# final destination of the packet # # @metric: Route metric # @@ -1899,7 +1905,8 @@ # # @use: Route usage count (not for windows) # -# @window: TCP window size, used for flow control (not for windows, IPv4 only) +# @window: TCP window size, used for flow control (not for windows, +# IPv4 only) # # @mtu: Data link layer maximum packet size (not for windows) #