Proxmox-Port/qemu
1
0
Fork 0
mirror of https://github.com/qemu/qemu.git synced 2025-07-29 14:43:25 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

qapi: remove trivial "Returns:" sections

Browse Source 
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>
This commit is contained in:
John Snow 2025-07-11 01:10:44 -04:00 committed by Markus Armbruster
parent 636c96cd77
commit 0462da9d6b
15 changed files with 3 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
qapi/audio.json
View File

@ -537,8 +537,6 @@
#
# Return information about audiodev configuration
#
# Returns: array of @Audiodev
#
# Since: 8.0
##
{ 'command': 'query-audiodevs',

8
qapi/block-core.json
View File

@ -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

8
qapi/char.json
View File

@ -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::

2
qapi/cryptodev.json
View File

@ -98,8 +98,6 @@
#
# Return information about current crypto devices.
#
# Returns: a list of @QCryptodevInfo
#
# Since: 8.0
##
{ 'command': 'query-cryptodev', 'returns': ['QCryptodevInfo']}

24
qapi/machine.json
View File

@ -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'] }

12
qapi/migration.json
View File

@ -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',

2
qapi/misc-arm.json
View File

@ -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::

10
qapi/misc-i386.json
View File

@ -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::

7
qapi/misc.json
View File

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

4
qapi/rocker.json
View File

@ -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::

2
qapi/run-state.json
View File

@ -121,8 +121,6 @@
#
# Query the run status of the VM
#
# Returns: @StatusInfo reflecting the VM
#
# Since: 0.14
#
# .. qmp-example::

4
qapi/tpm.json
View File

@ -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::

8
qapi/ui.json
View File

@ -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',

2
qapi/virtio.json
View File

@ -849,8 +849,6 @@
#
# @unstable: This command is meant for debugging.
#
# Returns: VirtioQueueElement information
#
# Since: 7.2
#
# .. qmp-example::

2
qapi/yank.json
View File

@ -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::
#