qapi: remove trivial "Returns:" sections

The new qapidoc.py can generate "Returns" statements with type
information just fine, so we can remove it from the source where it
doesn't add anything particularly novel or helpful and just repeats the
type info.

This patch is fairly "gentle" and doesn't aggressively touch other
"Returns" lines that could be rephrased to omit repeating type
information; it only removes lines that appear appropriate to wholly
remove.

To help facilitate auto-generated placement, a few doc blocks have a
"TODO:" line inserted to help the placement algorithm differentiate the
introductory paragraph(s) from the rest of the documentation.

The auto-generated returns are in the exact same spot, except for
query-migrationthreads, query-machines, and
x-query-virtio-queue-element.  These auto-generation moves to a better
spot.

Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711051045.51110-4-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Two more Returns: removed, commit message amended to explain
auto-generated returns generated into a different spot]
Signed-off-by: Markus Armbruster <armbru@redhat.com>

diff --git a/qapi/audio.json b/qapi/audio.json
index 6a22ca384aa274abd80e2d83432421f35f51357a..53142080f7216d967748649ba6e6349212c9222a 100644 (file)
--- a/qapi/audio.json
+++ b/qapi/audio.json
@@ -537,8 +537,6 @@
 #
 # Return information about audiodev configuration
 #
-# Returns: array of @Audiodev
-#
 # Since: 8.0
 ##
 { 'command': 'query-audiodevs',

diff --git a/qapi/block-core.json b/qapi/block-core.json
index 8b413946ff840185784bfacfb7d4d473e4874b09..01bf41b8b08ffb08042b617c306a1171be3f380c 100644 (file)
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1951,8 +1951,6 @@
 # @flat: Omit the nested data about backing image ("backing-image"
 #     key) if true.  Default is false (Since 5.0)
 #
-# Returns: the list of BlockDeviceInfo
-#
 # Since: 2.0
 #
 # .. qmp-example::
@@ -2465,9 +2463,6 @@
 #
 # @unstable: This command is meant for debugging.
 #
-# Returns:
-#     BlockDirtyBitmapSha256
-#
 # Errors:
 #     - If @node is not a valid block device, DeviceNotFound
 #     - If @name is not found or if hashing has failed, GenericError
@@ -6203,9 +6198,6 @@
 #
 # @name: optional the snapshot's name to be deleted
 #
-# Returns:
-#     SnapshotInfo
-#
 # Errors:
 #     - If @device is not a valid block device, GenericError
 #     - If snapshot not found, GenericError

diff --git a/qapi/char.json b/qapi/char.json
index f38d04986dd5bc37089d2809471cd57e32356625..f0a53f742c8bee24c377551803a864fd36ac78cf 100644 (file)
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -38,8 +38,6 @@
 #
 # Return information about current character devices.
 #
-# Returns: a list of @ChardevInfo
-#
 # Since: 0.14
 #
 # .. qmp-example::
@@ -84,8 +82,6 @@
 #
 # Return information about character device backends.
 #
-# Returns: a list of @ChardevBackendInfo
-#
 # Since: 2.0
 #
 # .. qmp-example::
@@ -774,8 +770,6 @@
 #
 # @backend: backend type and parameters
 #
-# Returns: ChardevReturn.
-#
 # Since: 1.4
 #
 # .. qmp-example::
@@ -814,8 +808,6 @@
 #
 # @backend: new backend type and parameters
 #
-# Returns: ChardevReturn.
-#
 # Since: 2.10
 #
 # .. qmp-example::

diff --git a/qapi/cryptodev.json b/qapi/cryptodev.json
index 1f49e1822c0b2905672d5452d29e9787aefb8c39..eb309c22f86453f80324d915407c49d46033319f 100644 (file)
--- a/qapi/cryptodev.json
+++ b/qapi/cryptodev.json
@@ -98,8 +98,6 @@
 #
 # Return information about current crypto devices.
 #
-# Returns: a list of @QCryptodevInfo
-#
 # Since: 8.0
 ##
 { 'command': 'query-cryptodev', 'returns': ['QCryptodevInfo']}

diff --git a/qapi/machine.json b/qapi/machine.json
index 2d6a137f21e58a454f651e128d1d55764f0ec70b..2364893cba77b175d27c386ad0f21f13f4332ad2 100644 (file)
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -103,8 +103,6 @@
 #
 # Return information about all virtual CPUs.
 #
-# Returns: list of @CpuInfoFast
-#
 # Since: 2.12
 #
 # .. qmp-example::
@@ -220,8 +218,6 @@
 #
 # @unstable: Argument @compat-props is experimental.
 #
-# Returns: a list of MachineInfo
-#
 # Since: 1.2
 #
 # .. qmp-example::
@@ -270,8 +266,6 @@
 #
 # Return information on the current virtual machine.
 #
-# Returns: CurrentMachineParams
-#
 # Since: 4.0
 ##
 { 'command': 'query-current-machine', 'returns': 'CurrentMachineParams' }
@@ -293,8 +287,6 @@
 #
 # Return information about the target for this QEMU
 #
-# Returns: QemuTargetInfo
-#
 # Since: 1.2
 ##
 { 'command': 'query-target', 'returns': 'QemuTargetInfo' }
@@ -318,8 +310,6 @@
 #
 # Query the guest UUID information.
 #
-# Returns: The @UuidInfo for the guest
-#
 # Since: 0.14
 #
 # .. qmp-example::
@@ -471,8 +461,6 @@
 #
 # Return information about KVM acceleration
 #
-# Returns: @KvmInfo
-#
 # Since: 0.14
 #
 # .. qmp-example::
@@ -934,8 +922,6 @@
 #
 # Return information for all memory backends.
 #
-# Returns: a list of @Memdev.
-#
 # Since: 2.1
 #
 # .. qmp-example::
@@ -1051,8 +1037,6 @@
 #
 # TODO: Better documentation; currently there is none.
 #
-# Returns: a list of HotpluggableCPU objects.
-#
 # Since: 2.7
 #
 # .. qmp-example::
@@ -1174,9 +1158,6 @@
 #
 # Return information about the balloon device.
 #
-# Returns:
-#     @BalloonInfo
-#
 # Errors:
 #     - If the balloon driver is enabled but not functional because
 #       the KVM kernel module cannot support it, KVMMissingCap
@@ -1240,9 +1221,6 @@
 # Return the hv-balloon driver data contained in the last received
 # "STATUS" message from the guest.
 #
-# Returns:
-#     @HvBalloonInfo
-#
 # Errors:
 #     - If no hv-balloon device is present, guest memory status
 #       reporting is not enabled or no guest memory status report
@@ -2260,8 +2238,6 @@
 #
 # Return a list of supported virtual CPU definitions
 #
-# Returns: a list of CpuDefinitionInfo
-#
 # Since: 1.2
 ##
 { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'] }

diff --git a/qapi/migration.json b/qapi/migration.json
index 3bf97df5d89a856191dd77e1897265e303d0bc23..57653160eb813e22c4820cc3c54b1701762afaad 100644 (file)
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -326,8 +326,6 @@
 # is active there will be another json-object with RAM migration
 # status.
 #
-# Returns: @MigrationInfo
-#
 # Since: 0.14
 #
 # .. qmp-example::
@@ -577,8 +575,6 @@
 #
 # Return information about the current migration capabilities status
 #
-# Returns: @MigrationCapabilityStatus
-#
 # Since: 1.2
 #
 # .. qmp-example::
@@ -1364,8 +1360,6 @@
 #
 # Return information about the current migration parameters
 #
-# Returns: @MigrationParameters
-#
 # Since: 2.4
 #
 # .. qmp-example::
@@ -1946,7 +1940,7 @@
 #
 # Query replication status while the vm is running.
 #
-# Returns: A @ReplicationStatus object showing the status.
+# TODO: This line is a hack to separate the example from the body
 #
 # .. qmp-example::
 #
@@ -2000,7 +1994,7 @@
 #
 # Query COLO status while the vm is running.
 #
-# Returns: A @COLOStatus object showing the status.
+# TODO: This line is a hack to separate the example from the body
 #
 # .. qmp-example::
 #
@@ -2375,8 +2369,6 @@
 #
 # @deprecated: This command is deprecated with no replacement yet.
 #
-# Returns: @MigrationThreadInfo
-#
 # Since: 7.2
 ##
 { 'command': 'query-migrationthreads',

diff --git a/qapi/misc-arm.json b/qapi/misc-arm.json
index f5341372f5a89fb7840f31e622a87be7c7e4edfb..f9dd743b523b0302e3682995f8278e8d43afaa2c 100644 (file)
--- a/qapi/misc-arm.json
+++ b/qapi/misc-arm.json
@@ -36,8 +36,6 @@
 # On non-ARM targets this command will report an error as the GIC
 # technology is not applicable.
 #
-# Returns: a list of GICCapability objects.
-#
 # Since: 2.6
 #
 # .. qmp-example::

diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json
index 24a2e143f6c4032087acd8ca915f92c25e693c35..5c3c9a14e063fc81aa59731d983dda039da4c5e7 100644 (file)
--- a/qapi/misc-i386.json
+++ b/qapi/misc-i386.json
@@ -132,8 +132,6 @@
 # @enabled field is set to 'false' and the state of all other fields
 # is unspecified.
 #
-# Returns: @SevInfo
-#
 # Since: 2.12
 #
 # .. qmp-example::
@@ -214,8 +212,6 @@
 #
 # This is only supported on AMD X86 platforms with KVM enabled.
 #
-# Returns: SevCapability objects.
-#
 # Errors:
 #     - If SEV is not available on the platform, GenericError
 #
@@ -280,8 +276,6 @@
 # @mnonce: a random 16 bytes value encoded in base64 (it will be
 #     included in report)
 #
-# Returns: SevAttestationReport objects.
-#
 # Errors:
 #     - If the attestation report is unavailable, either due to an
 #       invalid guest configuration or because the guest has not
@@ -343,8 +337,6 @@
 #
 # Return information about configured SGX capabilities of guest
 #
-# Returns: @SgxInfo
-#
 # Since: 6.2
 #
 # .. qmp-example::
@@ -362,8 +354,6 @@
 #
 # Return information about SGX capabilities of host
 #
-# Returns: @SgxInfo
-#
 # Since: 6.2
 #
 # .. qmp-example::

diff --git a/qapi/misc.json b/qapi/misc.json
index a180c16db25d44aec15278558e256efd93141594..b19eb08606959ea06cdd257b8dfaecc023507654 100644 (file)
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -58,8 +58,6 @@
 #
 # Return the name information of a guest.
 #
-# Returns: @NameInfo of the guest
-#
 # Since: 0.14
 #
 # .. qmp-example::
@@ -334,9 +332,6 @@
 #
 # @opaque: A free-form string that can be used to describe the fd.
 #
-# Returns:
-#     @AddfdInfo
-#
 # Errors:
 #     - If file descriptor was not received, GenericError
 #     - If @fdset-id is a negative value, GenericError
@@ -417,8 +412,6 @@
 #
 # Return information describing all fd sets.
 #
-# Returns: A list of @FdsetInfo
-#
 # Since: 1.2
 #
 # .. note:: The list of fd sets is shared by all monitor connections.

diff --git a/qapi/rocker.json b/qapi/rocker.json
index e4949649526def4e653e9001e12cf600b9d5b469..5d2dbd260345c1c61310a74c7fb69b72eac4dbc4 100644 (file)
--- a/qapi/rocker.json
+++ b/qapi/rocker.json
@@ -30,8 +30,6 @@
 #
 # @name: switch name
 #
-# Returns: @Rocker information
-#
 # Since: 2.4
 #
 # .. qmp-example::
@@ -100,8 +98,6 @@
 #
 # @name: port name
 #
-# Returns: a list of @RockerPort information
-#
 # Since: 2.4
 #
 # .. qmp-example::

diff --git a/qapi/run-state.json b/qapi/run-state.json
index 083a3c5eb30b05a3a4e8d083e937fd60481470e1..76f14569ff8b8062ef7ff98b7409f2047a6168a2 100644 (file)
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -121,8 +121,6 @@
 #
 # Query the run status of the VM
 #
-# Returns: @StatusInfo reflecting the VM
-#
 # Since: 0.14
 #
 # .. qmp-example::

diff --git a/qapi/tpm.json b/qapi/tpm.json
index e66b107f1d07cc6e100b359794fedb4354bdb434..3f2850a5733d191dda70cd908002a803de4e5398 100644 (file)
--- a/qapi/tpm.json
+++ b/qapi/tpm.json
@@ -29,8 +29,6 @@
 #
 # Return a list of supported TPM models
 #
-# Returns: a list of TpmModel
-#
 # Since: 1.5
 #
 # .. qmp-example::
@@ -60,8 +58,6 @@
 #
 # Return a list of supported TPM types
 #
-# Returns: a list of TpmType
-#
 # Since: 1.5
 #
 # .. qmp-example::

diff --git a/qapi/ui.json b/qapi/ui.json
index f5e77ae19d715dcc5429138d942fb0269f7bb275..53489ab65f008dd53ead723745bfb9f3b02a3eb9 100644 (file)
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -328,8 +328,6 @@
 #
 # Return information about the current SPICE server
 #
-# Returns: @SpiceInfo
-#
 # Since: 0.14
 #
 # .. qmp-example::
@@ -660,8 +658,6 @@
 #
 # Return information about the current VNC server
 #
-# Returns: @VncInfo
-#
 # Since: 0.14
 #
 # .. qmp-example::
@@ -691,8 +687,6 @@
 #
 # Return a list of vnc servers.  The list can be empty.
 #
-# Returns: a list of @VncInfo2
-#
 # Since: 2.3
 ##
 { 'command': 'query-vnc-servers', 'returns': ['VncInfo2'],
@@ -1570,8 +1564,6 @@
 #
 # Return information about display configuration
 #
-# Returns: @DisplayOptions
-#
 # Since: 3.1
 ##
 { 'command': 'query-display-options',

diff --git a/qapi/virtio.json b/qapi/virtio.json
index 3cac0774f7af2abb5a5be1fd50ec1fdc2d07a7ab..f0753cde715d8adc33b6de83050779f7df705144 100644 (file)
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -849,8 +849,6 @@
 #
 # @unstable: This command is meant for debugging.
 #
-# Returns: VirtioQueueElement information
-#
 # Since: 7.2
 #
 # .. qmp-example::

diff --git a/qapi/yank.json b/qapi/yank.json
index d13a8e911714fa4f791e738234cce6095a38b849..c14de5229e2433d698e74ab84597b1391cb51745 100644 (file)
--- a/qapi/yank.json
+++ b/qapi/yank.json
@@ -104,7 +104,7 @@
 #
 # Query yank instances.  See @YankInstance for more information.
 #
-# Returns: list of @YankInstance
+# TODO: This line is a hack to separate the example from the body
 #
 # .. qmp-example::
 #