Skip to contentSkip to conversation

qga: Doc fixes and improvements

PATCH Superseded Markus Armbruster 2 participants 10 messages Jul 17, 2025

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

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
#1 lore raw

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.

Fixes commit 8e326d36dd16 (qga/linux: Add new api 'guest-network-get-route')
---
 qga/qapi-schema.json | 1 +
 1 file changed, 1 insertion(+)
qga/qapi-schema.json +1 -0
index 6d770f7b8e..a569a14b55 100644
@@ -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
Reviewed-by on v1 1/4
#2 lore raw

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')
---
 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 :|
#3 lore raw

PATCH 2/4 qga: Remove trivial "Returns:" sections

In reply to 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 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
index a569a14b55..a9cc9150dc 100644
@@ -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
Reviewed-by on v1 2/4
#4 lore raw

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 from

Return:
GuestAgentInfo -- GuestAgentInfo

to

Return:
GuestAgentInfo

The 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).

---
 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 :|
#5 lore raw

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
index a9cc9150dc..6c26ace3c9 100644
@@ -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
Reviewed-by on v1 3/4
#6 lore raw

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).

---
 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 :|
#7 lore raw

PATCH 4/4 qga: Add cross-references

In reply to 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.

---
 qga/qapi-schema.json | 50 ++++++++++++++++++++++----------------------
 1 file changed, 25 insertions(+), 25 deletions(-)
qga/qapi-schema.json +25 -25
index 6c26ace3c9..31d454999f 100644
@@ -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
Reviewed-by on v1 4/4
#8 lore raw

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.

---
 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 :|
#9 lore raw

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.

---
 qga/qapi-schema.json | 50 ++++++++++++++++++++++----------------------
 1 file changed, 25 insertions(+), 25 deletions(-)
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.  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 ?

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!