From: Markus Armbruster <armbru@redhat.com>
To: qemu-devel@nongnu.org
Cc: eblake@redhat.com, michael.roth@amd.com, kkostiuk@redhat.com,
jsnow@redhat.com, berrange@redhat.com
Subject: [PATCH v2 2/4] qga: Remove trivial "Returns:" sections
Date: Thu, 17 Jul 2025 13:52:44 +0200 [thread overview]
Message-ID: <20250717115246.3830007-3-armbru@redhat.com> (raw)
In-Reply-To: <20250717115246.3830007-1-armbru@redhat.com>
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).
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
---
qga/qapi-schema.json | 25 -------------------------
1 file changed, 25 deletions(-)
diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index a569a14b55..a9cc9150dc 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -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',
--
2.49.0
next prev parent reply other threads:[~2025-07-17 11:57 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-07-17 11:52 [PATCH v2 0/4] qga: Doc fixes and improvements Markus Armbruster
2025-07-17 11:52 ` [PATCH v2 1/4] qga: Fix guest-network-get-route return value documentation Markus Armbruster
2025-07-21 20:24 ` John Snow
2025-07-17 11:52 ` Markus Armbruster [this message]
2025-07-21 20:57 ` [PATCH v2 2/4] qga: Remove trivial "Returns:" sections John Snow
2025-07-17 11:52 ` [PATCH v2 3/4] qga: Rephrase return docs to avoid type name Markus Armbruster
2025-07-21 20:58 ` John Snow
2025-07-17 11:52 ` [PATCH v2 4/4] qga: Add cross-references Markus Armbruster
2025-07-17 11:54 ` Daniel P. Berrangé
2025-07-21 21:00 ` John Snow
2025-07-28 11:19 ` [PATCH v2 0/4] qga: Doc fixes and improvements Markus Armbruster
2025-07-28 11:26 ` Kostiantyn Kostiuk
2025-07-28 11:54 ` Markus Armbruster
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20250717115246.3830007-3-armbru@redhat.com \
--to=armbru@redhat.com \
--cc=berrange@redhat.com \
--cc=eblake@redhat.com \
--cc=jsnow@redhat.com \
--cc=kkostiuk@redhat.com \
--cc=michael.roth@amd.com \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).