qga: Doc fixes and improvements
cover qga: Doc fixes and improvements
This series touches only doc comments. I'd like to get it into 10.1.
Markus Armbruster (4):
qga: Fix guest-network-get-route return value documentation
qga: Remove trivial "Returns:" sections
qga: Rephrase return docs to avoid type name
qga: Add cross-references
qga/qapi-schema.json | 79 +++++++++++++++----------------------------- 1 file changed, 27 insertions(+), 52 deletions(-)
Signature · 1 line
2.49.0
PATCH 1/4 qga: Fix guest-network-get-route return value documentation
Tagged sections are only recognized at the beginning of a paragraph. guest-network-get-route's Returns: isn't, and therefore gets rendered as ordinary text within its paragraph:
Retrieve information about route of network. Returns: List of route info of guest.
Since there is no (recognized) Returns: section, the doc generator adds
Return:
[GuestNetworkRoute]
Note: only since recent commit 636c96cd77d (qapi: Fix undocumented return values by generating something).
Insert the required blank line so that Returns: is recognized. Result:
Retrieve information about route of network.
Return:
[GuestNetworkRoute] -- List of route info of guest.
--- qga/qapi-schema.json | 1 + 1 file changed, 1 insertion(+)
qga/qapi-schema.json +1 -0
@@ -1966,6 +1966,7 @@ # @guest-network-get-route: # # Retrieve information about route of network. +# # Returns: List of route info of guest. # # Since: 9.1
Signature · 1 line
2.49.0
Re: [PATCH 1/4] qga: Fix guest-network-get-route return value documentation
Quoted 21 lines · Markus Armbruster
Tagged sections are only recognized at the beginning of a paragraph. guest-network-get-route's Returns: isn't, and therefore gets rendered as ordinary text within its paragraph:
Retrieve information about route of network. Returns: List of route info of guest.
Since there is no (recognized) Returns: section, the doc generator adds
Return:
[GuestNetworkRoute]Note: only since recent commit
636c96cd77d(qapi: Fix undocumented return values by generating something).Insert the required blank line so that Returns: is recognized. Result:
Retrieve information about route of network.
Quoted 8 lines
Return:
[GuestNetworkRoute] -- List of route info of guest.Fixes commit 8e326d36dd16 (qga/linux: Add new api 'guest-network-get-route')Signed-off-by Markus Armbruster <[email protected]>--- qga/qapi-schema.json | 1 + 1 file changed, 1 insertion(+)
With regards,
Daniel
Signature · 3 lines
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
PATCH 2/4 qga: Remove trivial "Returns:" sections
In reply to Markus ArmbrusterThe QAPI doc generator recently started to auto-generate return documentation when there is no "Returns:" section (commit 636c96cd77d "qapi: Fix undocumented return values by generating something"). Remove "Returns:" sections where the auto-generated text is obviously no worse. For instance, guest-info's documentation changes from
Return:
GuestAgentInfo -- GuestAgentInfo
to
Return:
GuestAgentInfo
The auto-generated returns all are in the exact same spot.
We did this for qapi/ in commit 0462da9d6b1 (qapi: remove trivial "Returns:" sections).
--- qga/qapi-schema.json | 25 ------------------------- 1 file changed, 25 deletions(-)
qga/qapi-schema.json +0 -25
@@ -202,8 +202,6 @@ # # Get some information about the guest agent. # -# Returns: @GuestAgentInfo -# # Since: 0.15.0 ## { 'command': 'guest-info',
@@ -285,8 +283,6 @@ # @count: maximum number of bytes to read (default is 4KB, maximum is # 48MB) # -# Returns: @GuestFileRead -# # Since: 0.15.0 ## { 'command': 'guest-file-read',
@@ -320,8 +316,6 @@ # @count: bytes to write (actual bytes, after base64-decode), default # is all content in buf-b64 buffer after base64 decoding # -# Returns: @GuestFileWrite -# # Since: 0.15.0 ## { 'command': 'guest-file-write',
@@ -387,8 +381,6 @@ # # @whence: Symbolic or numeric code for interpreting offset # -# Returns: @GuestFileSeek -# # Since: 0.15.0 ## { 'command': 'guest-file-seek',
@@ -428,9 +420,6 @@ # # Get guest fsfreeze state. # -# Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined -# below) -# # .. note:: This may fail to properly report the current state as a # result of some other guest processes having issued an fs # freeze/thaw.
@@ -749,8 +738,6 @@ # # Get list of guest IP addresses, MAC addresses and netmasks. # -# Returns: List of GuestNetworkInterface -# # Since: 1.1 ## { 'command': 'guest-network-get-interfaces',
@@ -1251,8 +1238,6 @@ # # Get information relating to guest memory blocks. # -# Returns: @GuestMemoryBlockInfo -# # Since: 2.3 ## { 'command': 'guest-get-memory-block-info',
@@ -1298,8 +1283,6 @@ # # @pid: pid returned from guest-exec # -# Returns: GuestExecStatus -# # Since: 2.5 ## { 'command': 'guest-exec-status',
@@ -1458,8 +1441,6 @@ # # Retrieves the timezone information from the guest. # -# Returns: A GuestTimezone dictionary. -# # Since: 2.10 ## { 'command': 'guest-get-timezone',
@@ -1533,8 +1514,6 @@ # # Retrieve guest operating system information # -# Returns: @GuestOSInfo -# # Since: 2.10 ## { 'command': 'guest-get-osinfo',
@@ -1604,8 +1583,6 @@ # # Retrieve information about device drivers in Windows guest # -# Returns: @GuestDeviceInfo -# # Since: 5.2 ## { 'command': 'guest-get-devices',
@@ -1633,8 +1610,6 @@ # # @username: the user account to add the authorized keys # -# Returns: @GuestAuthorizedKeys -# # Since: 5.2 ## { 'command': 'guest-ssh-get-authorized-keys',
Signature · 1 line
2.49.0
Re: [PATCH 2/4] qga: Remove trivial "Returns:" sections
Quoted 16 lines · Markus Armbruster
The QAPI doc generator recently started to auto-generate return documentation when there is no "Returns:" section (commit
636c96cd77d"qapi: Fix undocumented return values by generating something"). Remove "Returns:" sections where the auto-generated text is obviously no worse. For instance, guest-info's documentation changes fromReturn:
GuestAgentInfo -- GuestAgentInfoto
Return:
GuestAgentInfoThe auto-generated returns all are in the exact same spot.
Quoted 7 lines
We did this for qapi/ in commit
0462da9d6b1(qapi: remove trivial "Returns:" sections).Signed-off-by Markus Armbruster <[email protected]>--- qga/qapi-schema.json | 25 ------------------------- 1 file changed, 25 deletions(-)
With regards,
Daniel
Signature · 3 lines
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
PATCH 3/4 qga: Rephrase return docs to avoid type name
In reply to Markus Armbruster"Returns: <description>" is rendered like
Return: <Type> – <description>
Mentioning the type in the description again is commonly redundant. There is just one such description. Rephrase it not to mention the type.
We did this for qapi/ in commit f7296f8de5c (qapi: rephrase return docs to avoid type name).
--- qga/qapi-schema.json | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-)
qga/qapi-schema.json +1 -2
@@ -534,8 +534,7 @@ # discarded. The default value is zero, meaning "discard every # free block". # -# Returns: A @GuestFilesystemTrimResponse which contains the status of -# all trimmed paths. (since 2.4) +# Returns: status of all trimmed paths. (since 2.4) # # Since: 1.2 ##
Signature · 1 line
2.49.0
Re: [PATCH 3/4] qga: Rephrase return docs to avoid type name
Quoted 8 lines · Markus Armbruster
"Returns: <description>" is rendered like
Return: <Type> – <description>
Mentioning the type in the description again is commonly redundant. There is just one such description. Rephrase it not to mention the type.
Quoted 7 lines
We did this for qapi/ in commit
f7296f8de5c(qapi: rephrase return docs to avoid type name).Signed-off-by Markus Armbruster <[email protected]>--- qga/qapi-schema.json | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-)
With regards,
Daniel
Signature · 3 lines
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
PATCH 4/4 qga: Add cross-references
In reply to Markus ArmbrusterEnclose command and type names in backquotes, so they become links in generated HTML.
We did this for qapi/ in merge commit 504632dcc631.
--- qga/qapi-schema.json | 50 ++++++++++++++++++++++---------------------- 1 file changed, 25 insertions(+), 25 deletions(-)
qga/qapi-schema.json +25 -25
@@ -96,11 +96,11 @@ # 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 +# 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 +# JSON objects, `guest-sync` should be sufficient, but note that in # cases where the channel is dirty some attempts at parsing the # response may result in a parser error. #
@@ -247,7 +247,7 @@ # # Close an open file in the guest # -# @handle: filehandle returned by guest-file-open +# @handle: filehandle returned by `guest-file-open` # # Since: 0.15.0 ##
@@ -278,7 +278,7 @@ # As this command is just for limited, ad-hoc debugging, such as log # file access, the number of bytes to read is limited to 48 MB. # -# @handle: filehandle returned by guest-file-open +# @handle: filehandle returned by `guest-file-open` # # @count: maximum number of bytes to read (default is 4KB, maximum is # 48MB)
@@ -309,7 +309,7 @@ # # Write to an open file in the guest. # -# @handle: filehandle returned by guest-file-open +# @handle: filehandle returned by `guest-file-open` # # @buf-b64: base64-encoded string representing data to be written #
@@ -340,7 +340,7 @@ ## # @QGASeek: # -# Symbolic names for use in @guest-file-seek +# Symbolic names for use in `guest-file-seek` # # @set: Set to the specified offset (same effect as 'whence':0) #
@@ -355,7 +355,7 @@ ## # @GuestFileWhence: # -# Controls the meaning of offset to @guest-file-seek. +# Controls the meaning of offset to `guest-file-seek`. # # @value: Integral value (0 for set, 1 for cur, 2 for end), available # for historical reasons, and might differ from the host's or
@@ -375,7 +375,7 @@ # current file position afterward. Also encapsulates ftell()'s # functionality, with offset=0 and whence=1. # -# @handle: filehandle returned by guest-file-open +# @handle: filehandle returned by `guest-file-open` # # @offset: bytes to skip over in the file stream #
@@ -393,7 +393,7 @@ # # Write file changes buffered in userspace to disk/kernel buffers # -# @handle: filehandle returned by guest-file-open +# @handle: filehandle returned by `guest-file-open` # # Since: 0.15.0 ##
@@ -434,12 +434,12 @@ # @guest-fsfreeze-freeze: # # Sync and freeze all freezable, local guest filesystems. If this -# command succeeded, you may call @guest-fsfreeze-thaw later to +# command succeeded, you may call `guest-fsfreeze-thaw` later to # unfreeze. # # On error, all filesystems will be thawed. If no filesystems are -# frozen as a result of this call, then @guest-fsfreeze-status will -# remain "thawed" and calling @guest-fsfreeze-thaw is not necessary. +# frozen as a result of this call, then `guest-fsfreeze-status` will +# remain "thawed" and calling `guest-fsfreeze-thaw` is not necessary. # # Returns: Number of file systems currently frozen. #
@@ -457,7 +457,7 @@ # @guest-fsfreeze-freeze-list: # # Sync and freeze specified guest filesystems. See also -# @guest-fsfreeze-freeze. +# `guest-fsfreeze-freeze`. # # On error, all filesystems will be thawed. #
@@ -482,7 +482,7 @@ # 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 +# `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. #
@@ -513,7 +513,7 @@ ## # @GuestFilesystemTrimResponse: # -# @paths: list of @GuestFilesystemTrimResult per path that was trimmed +# @paths: list of `GuestFilesystemTrimResult` per path that was trimmed # # Since: 2.4 ##
@@ -565,7 +565,7 @@ # Errors: # - If suspend to disk is not supported, Unsupported # -# .. note:: It's strongly recommended to issue the guest-sync command +# .. note:: It's strongly recommended to issue the `guest-sync` command # before sending commands when the guest resumes. # # Since: 1.1
@@ -585,7 +585,7 @@ # - pm-utils (via pm-hibernate) # - manual write into sysfs # -# IMPORTANT: guest-suspend-ram requires working wakeup support in +# IMPORTANT: `guest-suspend-ram` requires working wakeup support in # 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
@@ -602,7 +602,7 @@ # Errors: # - If suspend to ram is not supported, Unsupported # -# .. note:: It's strongly recommended to issue the guest-sync command +# .. note:: It's strongly recommended to issue the `guest-sync` command # before sending commands when the guest resumes. # # Since: 1.1
@@ -621,7 +621,7 @@ # - systemd hybrid-sleep # - pm-utils (via pm-suspend-hybrid) # -# IMPORTANT: guest-suspend-hybrid requires working wakeup support in +# IMPORTANT: `guest-suspend-hybrid` requires working wakeup support in # 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
@@ -638,7 +638,7 @@ # Errors: # - If hybrid suspend is not supported, Unsupported # -# .. note:: It's strongly recommended to issue the guest-sync command +# .. note:: It's strongly recommended to issue the `guest-sync` command # before sending commands when the guest resumes. # # Since: 1.1
@@ -1171,7 +1171,7 @@ ## # @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. #
@@ -1277,10 +1277,10 @@ # @guest-exec-status: # # Check status of process associated with PID retrieved via -# guest-exec. Reap the process and associated metadata if it has +# `guest-exec`. Reap the process and associated metadata if it has # exited. # -# @pid: pid returned from guest-exec +# @pid: pid returned from `guest-exec` # # Since: 2.5 ##
@@ -1301,7 +1301,7 @@ ## # @GuestExecCaptureOutputMode: # -# An enumeration of guest-exec capture modes. +# An enumeration of `guest-exec` capture modes. # # @none: do not capture any output #
@@ -1324,7 +1324,7 @@ ## # @GuestExecCaptureOutput: # -# Controls what guest-exec output gets captures. +# Controls what `guest-exec` output gets captures. # # @flag: captures both stdout and stderr if true. Equivalent to # GuestExecCaptureOutputMode::all. (since 2.5)
Signature · 1 line
2.49.0
Re: [PATCH 4/4] qga: Add cross-references
Quoted 9 lines · Markus Armbruster
Enclose command and type names in
backquotes, so they become links in generated HTML.We did this for qapi/ in merge commit
504632dcc631.Signed-off-by Markus Armbruster <[email protected]>--- qga/qapi-schema.json | 50 ++++++++++++++++++++++---------------------- 1 file changed, 25 insertions(+), 25 deletions(-)
qga/qapi-schema.json line 590
Quoted 8 lines
qga/qapi-schema.json +1
-1@@ -585,7 +585,7 @@ # - pm-utils (via pm-hibernate) # - manual write into sysfs # -# IMPORTANT: guest-suspend-ram requires working wakeup support in +# IMPORTANT: `guest-suspend-ram` requires working wakeup support in # QEMU. You should check QMP command query-current-machine returns # wakeup-suspend-support: true before issuing this command. Failure
I presume you're not updating 'query-current-machine' and 'wakeup-suspend-support' due to an inability do cross references across the two QAPI schemas ?
With regards,
Daniel
Signature · 3 lines
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
Re: [PATCH 4/4] qga: Add cross-references
Quoted 14 lines · Daniel P. Berrangé
Quoted 9 lines · Markus Armbruster
Enclose command and type names in
backquotes, so they become links in generated HTML.We did this for qapi/ in merge commit
504632dcc631.Signed-off-by Markus Armbruster <[email protected]>--- qga/qapi-schema.json | 50 ++++++++++++++++++++++---------------------- 1 file changed, 25 insertions(+), 25 deletions(-)Reviewed-by Daniel P. Berrangé <[email protected]>
Quoted 12 lines
qga/qapi-schema.json line 590
Quoted 8 lines
qga/qapi-schema.json +1
-1@@ -585,7 +585,7 @@ # - pm-utils (via pm-hibernate) # - manual write into sysfs # -# IMPORTANT: guest-suspend-ram requires working wakeup support in +# IMPORTANT: `guest-suspend-ram` requires working wakeup support in # QEMU. You should check QMP command query-current-machine returns # wakeup-suspend-support: true before issuing this command. FailureI presume you're not updating 'query-current-machine' and 'wakeup-suspend-support' due to an inability do cross references across the two QAPI schemas ?
I'm not updating them because I missed them!
Putting query-current-machine in backquotes just works. There are a few more. I'll respin.
I don't know how to reference a member of a type from outside the type. Left for later.
Thanks!