qapi: rephrase return docs to avoid type name

"Returns: <description>" is rendered like "Return: <Type> –
<description>".  Mentioning the type in the description again is
commonly redundant.  Rephrase such descriptions not to.

Well, I tried. Maybe not very hard. Sorry!

Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250711051045.51110-5-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
[Commit message amended to explain why]
Signed-off-by: Markus Armbruster <armbru@redhat.com>

diff --git a/qapi/block-core.json b/qapi/block-core.json
index 01bf41b8b08ffb08042b617c306a1171be3f380c..848ebaff5a82d789f70cebbf924d1c46cc40bc9b 100644 (file)
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -764,7 +764,7 @@
 #
 # Get a list of BlockInfo for all virtual block devices.
 #
-# Returns: a list of @BlockInfo describing each virtual block device.
+# Returns: a list describing each virtual block device.
 #     Filter nodes that were created implicitly are skipped over.
 #
 # Since: 0.14
@@ -1169,7 +1169,7 @@
 #     nodes that were created implicitly are skipped over in this
 #     mode.  (Since 2.3)
 #
-# Returns: A list of @BlockStats for each virtual block devices.
+# Returns: A list of statistics for each virtual block device.
 #
 # Since: 0.14
 #
@@ -1441,7 +1441,7 @@
 #
 # Return information about long-running block device operations.
 #
-# Returns: a list of @BlockJobInfo for each active block job
+# Returns: a list of job info for each active block job
 #
 # Since: 1.1
 ##

diff --git a/qapi/block-export.json b/qapi/block-export.json
index 2241bfecf2585550b8fb59cf05e4abd949a8c9d6..fb004e35fdc84d0277aebde3424fbc112c3fff2d 100644 (file)
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -473,7 +473,7 @@
 ##
 # @query-block-exports:
 #
-# Returns: A list of BlockExportInfo describing all block exports
+# Returns: A list describing all block exports
 #
 # Since: 5.2
 ##

diff --git a/qapi/block.json b/qapi/block.json
index 2d54a81c366cf25982ccfbbc72a3b999540feb2a..f0436ce871027e51bbbe2d2a95bb6657c68dfe56 100644 (file)
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -89,7 +89,7 @@
 # Return a list of information about each persistent reservation
 # manager.
 #
-# Returns: a list of @PRManagerInfo for each persistent reservation
+# Returns: a list of manager info for each persistent reservation
 #     manager
 #
 # Since: 3.0

diff --git a/qapi/control.json b/qapi/control.json
index 5fed0701f83ca10ba7a996b8208e8fea241e896f..931a860b3061775e15f1cd5c279925725dc02bb0 100644 (file)
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -95,8 +95,7 @@
 #
 # Return the current version of QEMU.
 #
-# Returns: A @VersionInfo object describing the current version of
-#     QEMU.
+# Returns: An object describing the current version of QEMU.
 #
 # Since: 0.14
 #
@@ -133,7 +132,7 @@
 #
 # Return a list of supported QMP commands by this server
 #
-# Returns: A list of @CommandInfo for all supported commands
+# Returns: A list of all supported commands
 #
 # Since: 0.14
 #

diff --git a/qapi/dump.json b/qapi/dump.json
index 0642ca157b8a750af6aace4195165a2e8980cd58..dc92b5324700a0e0daf026db3ea39a5b1ce423bf 100644 (file)
--- a/qapi/dump.json
+++ b/qapi/dump.json
@@ -148,7 +148,7 @@
 #
 # Query latest dump status.
 #
-# Returns: A @DumpStatus object showing the dump status.
+# Returns: An object showing the dump status.
 #
 # Since: 2.6
 #
@@ -199,8 +199,7 @@
 #
 # Return the available formats for dump-guest-memory
 #
-# Returns: A @DumpGuestMemoryCapability object listing available
-#     formats for dump-guest-memory
+# Returns: An object listing available formats for dump-guest-memory
 #
 # Since: 2.0
 #

diff --git a/qapi/introspect.json b/qapi/introspect.json
index 26d8839f19c4a26ce1d8ce5be884d050b4ba5ee7..be8511b067266ed0bc8bec2aa47ecd084639a50b 100644 (file)
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -36,10 +36,10 @@
 # string into a specific enum or from one specific type into an
 # alternate that includes the original type alongside something else.
 #
-# Returns: array of @SchemaInfo, where each element describes an
-#     entity in the ABI: command, event, type, ...
+# Returns: an array where each element describes an entity in the ABI:
+#     command, event, type, ...
 #
-#     The order of the various SchemaInfo is unspecified; however, all
+#     The order of the various elements is unspecified; however, all
 #     names are guaranteed to be unique (no name will be duplicated
 #     with different meta-types).
 #

diff --git a/qapi/job.json b/qapi/job.json
index 16b280f52f8ff097729ca0367427f9d4cf60a232..51a57c523e09891977c566f005831705f0066dd0 100644 (file)
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -297,7 +297,7 @@
 #
 # Return information about jobs.
 #
-# Returns: a list with a @JobInfo for each active job
+# Returns: a list with info for each active job
 #
 # Since: 3.0
 ##

diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json
index 5c3c9a14e063fc81aa59731d983dda039da4c5e7..282bd3627bb80ec85bba2566e1b0929902f1ce7d 100644 (file)
--- a/qapi/misc-i386.json
+++ b/qapi/misc-i386.json
@@ -163,7 +163,7 @@
 # 'sev-guest' confidential virtualization object.  The launch
 # measurement for SEV-SNP guests is only available within the guest.
 #
-# Returns: The @SevLaunchMeasureInfo for the guest
+# Returns: The guest's SEV guest launch measurement info
 #
 # Errors:
 #     - If the launch measurement is unavailable, either due to an

diff --git a/qapi/misc.json b/qapi/misc.json
index b19eb08606959ea06cdd257b8dfaecc023507654..7dbc29dbd6d3b375f1b8594090652cfa279cba5f 100644 (file)
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -107,7 +107,7 @@
 #    declared using the ``-object iothread`` command-line option.  It
 #    is always the main thread of the process.
 #
-# Returns: a list of @IOThreadInfo for each iothread
+# Returns: a list of info for each iothread
 #
 # Since: 2.0
 #
@@ -511,8 +511,7 @@
 #
 # @option: option name
 #
-# Returns: list of @CommandLineOptionInfo for all options (or for the
-#     given @option).
+# Returns: list of objects for all options (or for the given @option).
 #
 # Errors:
 #     - if the given @option doesn't exist

diff --git a/qapi/net.json b/qapi/net.json
index 3b03843c1650774c3bedc927ad2ea23d71bebe5d..a266c6786e2992f9145c92417155a834894cbfd6 100644 (file)
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -847,7 +847,7 @@
 #
 # @name: net client name
 #
-# Returns: list of @RxFilterInfo for all NICs (or for the given NIC).
+# Returns: list of info for all NICs (or for the given NIC).
 #
 # Errors:
 #     - if the given @name doesn't exist

diff --git a/qapi/pci.json b/qapi/pci.json
index a8671cd9ac32285612ae3a41a548674f34ea95b0..418ea4fc9321c7d473994b77e1f123df3ed7fa0a 100644 (file)
--- a/qapi/pci.json
+++ b/qapi/pci.json
@@ -177,7 +177,7 @@
 #
 # Return information about the PCI bus topology of the guest.
 #
-# Returns: a list of @PciInfo for each PCI bus.  Each bus is
+# Returns: a list of info for each PCI bus.  Each bus is
 #     represented by a json-object, which has a key with a json-array
 #     of all PCI devices attached to it.  Each device is represented
 #     by a json-object.

diff --git a/qapi/qdev.json b/qapi/qdev.json
index 441ed518b878be3640f321e051a0ef504d55cee1..6441357e009b990132712cfe91e069cb265b0f92 100644 (file)
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -19,8 +19,7 @@
 #
 # @typename: the type name of a device
 #
-# Returns: a list of ObjectPropertyInfo describing a devices
-#     properties
+# Returns: a list describing a devices properties
 #
 # .. note:: Objects can create properties at runtime, for example to
 #    describe links between different devices and/or objects.  These

diff --git a/qapi/qom.json b/qapi/qom.json
index fbf94b9e09d2010c639134457189173211e671ad..aa09eddbf9d444804d906f3ae6d5d200cda3be11 100644 (file)
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -55,8 +55,7 @@
 # @path: the path within the object model.  See @qom-get for a
 #     description of this parameter.
 #
-# Returns: a list of @ObjectPropertyInfo that describe the properties
-#     of the object.
+# Returns: a list that describe the properties of the object.
 #
 # Since: 1.2
 #
@@ -178,8 +177,7 @@
 #
 # @abstract: if true, include abstract types in the results
 #
-# Returns: a list of @ObjectTypeInfo or an empty list if no results
-#     are found
+# Returns: a list of types, or an empty list if no results are found
 #
 # Since: 1.1
 ##
@@ -199,7 +197,7 @@
 #    describe links between different devices and/or objects.  These
 #    properties are not included in the output of this command.
 #
-# Returns: a list of ObjectPropertyInfo describing object properties
+# Returns: a list describing object properties
 #
 # Since: 2.12
 ##

diff --git a/qapi/stats.json b/qapi/stats.json
index 78b88881eabfe15ac9ffd183cec3504850a57288..b63a7369dd1e4f391988cc38e4dac117bd703850 100644 (file)
--- a/qapi/stats.json
+++ b/qapi/stats.json
@@ -188,7 +188,7 @@
 # The arguments are a StatsFilter and specify the provider and objects
 # to return statistics about.
 #
-# Returns: a list of StatsResult, one for each provider and object
+# Returns: a list of statistics, one for each provider and object
 #     (e.g., for each vCPU).
 #
 # Since: 7.1

diff --git a/qapi/trace.json b/qapi/trace.json
index d08c9c6a8897adfbbcccb2b489698dbaa1de9a73..de369dae6b531809fc66c89801c2036ec9e25adc 100644 (file)
--- a/qapi/trace.json
+++ b/qapi/trace.json
@@ -49,7 +49,7 @@
 #
 # @name: Event name pattern (case-sensitive glob).
 #
-# Returns: a list of @TraceEventInfo for the matching events
+# Returns: a list of info for the matching events
 #
 # Since: 2.2
 #

diff --git a/qapi/ui.json b/qapi/ui.json
index 53489ab65f008dd53ead723745bfb9f3b02a3eb9..b48266c458bf6956e3e350f31866ff47df81cb43 100644 (file)
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -822,7 +822,7 @@
 #
 # Return information about each active mouse device
 #
-# Returns: a list of @MouseInfo for each device
+# Returns: a list of info for each device
 #
 # Since: 0.14
 #

diff --git a/qapi/virtio.json b/qapi/virtio.json
index f0753cde715d8adc33b6de83050779f7df705144..2e23512085ed18121f3c2460c2e85b30bfa1406d 100644 (file)
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -201,7 +201,7 @@
 #
 # @unstable: This command is meant for debugging.
 #
-# Returns: VirtioStatus of the virtio device
+# Returns: Status of the virtio device
 #
 # Since: 7.2
 #
@@ -565,7 +565,7 @@
 #
 # @unstable: This command is meant for debugging.
 #
-# Returns: VirtQueueStatus of the VirtQueue
+# Returns: Status of the queue
 #
 # .. note:: last_avail_idx will not be displayed in the case where the
 #    selected VirtIODevice has a running vhost device and the
@@ -700,7 +700,7 @@
 #
 # @unstable: This command is meant for debugging.
 #
-# Returns: VirtVhostQueueStatus of the vhost_virtqueue
+# Returns: Status of the vhost_virtqueue
 #
 # Since: 7.2
 #