| Message ID | 20250326195756.330817-5-jsnow@redhat.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | qapi: add auto-generated return docs | expand |
John Snow <jsnow@redhat.com> writes: > Well, I tried. Maybe not very hard. Sorry! No need to be sorry! Kick-starting discussion with limited effort is better than a big effort going into a direction that turns out to be unwanted once we discuss it. Instead of just rephrasing Returns descriptions, I'd like us to consider both Returns and intro. See below for why. > Signed-off-by: John Snow <jsnow@redhat.com> > --- > qapi/block-core.json | 6 +++--- > qapi/block-export.json | 2 +- > qapi/block.json | 2 +- > qapi/control.json | 5 ++--- > qapi/dump.json | 5 ++--- > qapi/introspect.json | 6 +++--- > qapi/job.json | 2 +- > qapi/machine-target.json | 7 +++---- > qapi/misc-target.json | 2 +- > qapi/misc.json | 5 ++--- > qapi/net.json | 2 +- > qapi/pci.json | 2 +- > qapi/qdev.json | 3 +-- > qapi/qom.json | 8 +++----- > qapi/stats.json | 2 +- > qapi/trace.json | 2 +- > qapi/ui.json | 2 +- > qapi/virtio.json | 6 +++--- > 18 files changed, 31 insertions(+), 38 deletions(-) > > diff --git a/qapi/block-core.json b/qapi/block-core.json > index 92b2e368b72..eb97b70cd80 100644 > --- a/qapi/block-core.json > +++ b/qapi/block-core.json > @@ -763,7 +763,7 @@ ## # @query-block: > # > # 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 > @@ -1168,7 +1168,7 @@ ## # @query-blockstats: # # Query the @BlockStats for all virtual block devices. # # @query-nodes: If true, the command will query all the block nodes # that have a node name, in a list which will include "parent" # information, but not "backing". If false or omitted, the # behavior is as before - query all the device backends, # recursively including their "parent" and "backing". Filter > # 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 > # > @@ -1440,7 +1440,7 @@ ## # @query-block-jobs: > # > # 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 > ## Stopping here, because I believe this is already enough to make a useful observation. There's overlap between query-FOO's intro and Returns. The intro describes the command's purpose, and the purpose of a query-FOO is to return certain information. Returns describes the value returned. Both talk about the same thing, namely the value returned. Why two prose descriptions of the value returned? Wouldn't one be better? Let's try. We need to choose where to put it, intro or Returns. When Returns comes right after intro, putting it into Returns can work fine, because the command's purpose still comes first. For instance: ## # @query-block: # # Return information about all virtual block devices. Filter nodes # that were created implicitly are skipped over. renders like Command query-block (Since: 0.14) Return information about all virtual block devices. Filter nodes that were created implicitly are skipped over. Return: ["BlockInfo"] and ## # @query-block: # # Returns: Information about all virtual block devices. # Filter nodes that were created implicitly are skipped over. renders like Command query-block (Since: 0.14) Return: ["BlockInfo"] -- Information about all virtual block devices. Filter nodes that were created implicitly are skipped over. Both work. But when there's something in between, intro is preferable. For instance: ## # @query-blockstats: # # Return statistics for all virtual block devices. # # @query-nodes: If true, the command will query all the block nodes # that have a node name, in a list which will include "parent" # information, but not "backing". If false or omitted, the # behavior is as before - query all the device backends, # recursively including their "parent" and "backing". Filter # nodes that were created implicitly are skipped over in this # mode. (Since 2.3) renders like Command query-blockstats (Since: 0.14) Return statistics for all virtual block devices. Arguments: * **query-nodes** ("boolean", *optional*) -- If true, the command will query all the block nodes that have a node name, in a list which will include "parent" information, but not "backing". If false or omitted, the behavior is as before - query all the device backends, recursively including their "parent" and "backing". Filter nodes that were created implicitly are skipped over in this mode. (Since 2.3) Return: ["BlockStats"] while ## # @query-blockstats: # # @query-nodes: If true, the command will query all the block nodes # that have a node name, in a list which will include "parent" # information, but not "backing". If false or omitted, the # behavior is as before - query all the device backends, # recursively including their "parent" and "backing". Filter # nodes that were created implicitly are skipped over in this # mode. (Since 2.3) # # Returns: Statistics for all virtual block devices renders like Command query-blockstats (Since: 0.14) Arguments: * **query-nodes** ("boolean", *optional*) -- If true, the command will query all the block nodes that have a node name, in a list which will include "parent" information, but not "backing". If false or omitted, the behavior is as before - query all the device backends, recursively including their "parent" and "backing". Filter nodes that were created implicitly are skipped over in this mode. (Since 2.3) Return: ["BlockStats"] -- Statistics for all virtual block devices I much prefer the former, because it puts the command's purpose where it belongs: first. Perhaps we should simply use the intro always. Thoughts?
diff --git a/qapi/block-core.json b/qapi/block-core.json index 92b2e368b72..eb97b70cd80 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -763,7 +763,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 @@ -1168,7 +1168,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 # @@ -1440,7 +1440,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 c783e01a532..84852606e52 100644 --- a/qapi/block-export.json +++ b/qapi/block-export.json @@ -472,7 +472,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 e66666f5c64..bdbbe78854f 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -86,7 +86,7 @@ # Returns 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 336386f79e1..2e45bf25df8 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -93,8 +93,7 @@ # # Returns 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 # @@ -131,7 +130,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 d7826c0e323..1bd6bacc5ce 100644 --- a/qapi/dump.json +++ b/qapi/dump.json @@ -146,7 +146,7 @@ # # Query latest dump status. # -# Returns: A @DumpStatus object showing the dump status. +# Returns: An object showing the dump status. # # Since: 2.6 # @@ -197,8 +197,7 @@ # # Returns 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 01bb242947c..7daec5045fb 100644 --- a/qapi/introspect.json +++ b/qapi/introspect.json @@ -34,10 +34,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 cfc3beedd21..856dd688f95 100644 --- a/qapi/job.json +++ b/qapi/job.json @@ -269,7 +269,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/machine-target.json b/qapi/machine-target.json index 37e75520094..6d8a6e53436 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -162,8 +162,7 @@ # @modelb: description of the second CPU model to compare, referred to # as "model B" in CpuModelCompareResult # -# Returns: a CpuModelCompareInfo describing how both CPU models -# compare +# Returns: An object describing how both CPU models compare # # Errors: # - if comparing CPU models is not supported @@ -218,7 +217,7 @@ # # @modelb: description of the second CPU model to baseline # -# Returns: a CpuModelBaselineInfo describing the baselined CPU model +# Returns: An object describing the baselined CPU model # # Errors: # - if baselining CPU models is not supported @@ -296,7 +295,7 @@ # # @type: expansion type, specifying how to expand the CPU model # -# Returns: a CpuModelExpansionInfo describing the expanded CPU model +# Returns: An object describing the expanded CPU model # # Errors: # - if expanding CPU models is not supported diff --git a/qapi/misc-target.json b/qapi/misc-target.json index 59a8f5b2bed..295d63df76b 100644 --- a/qapi/misc-target.json +++ b/qapi/misc-target.json @@ -158,7 +158,7 @@ # # Query the SEV guest launch information. # -# Returns: The @SevLaunchMeasureInfo for the guest +# Returns: The guest's SEV guest launch measurement info # # Since: 2.12 # diff --git a/qapi/misc.json b/qapi/misc.json index de5dd531071..3d10aeb215c 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -105,7 +105,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 # @@ -509,8 +509,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 310cc4fd190..43739fd0259 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -845,7 +845,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 dc85a41d28b..29549d94551 100644 --- a/qapi/pci.json +++ b/qapi/pci.json @@ -175,7 +175,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 25cbcf977b4..55a509071e9 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -17,8 +17,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 28ce24cd8d0..b053e8bf0c7 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -54,8 +54,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 8902ef94e08..7e7f1dabbc3 100644 --- a/qapi/stats.json +++ b/qapi/stats.json @@ -186,7 +186,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 eb5f63f5135..11f0b5c3427 100644 --- a/qapi/trace.json +++ b/qapi/trace.json @@ -47,7 +47,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 46843bdbefa..a1015801b1b 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -816,7 +816,7 @@ # # Returns 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 93c576a21da..cee0e100d44 100644 --- a/qapi/virtio.json +++ b/qapi/virtio.json @@ -199,7 +199,7 @@ # # @unstable: This command is meant for debugging. # -# Returns: VirtioStatus of the virtio device +# Returns: Status of the virtio device # # Since: 7.2 # @@ -563,7 +563,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 @@ -698,7 +698,7 @@ # # @unstable: This command is meant for debugging. # -# Returns: VirtVhostQueueStatus of the vhost_virtqueue +# Returns: Status of the vhost_virtqueue # # Since: 7.2 #
Well, I tried. Maybe not very hard. Sorry! Signed-off-by: John Snow <jsnow@redhat.com> --- qapi/block-core.json | 6 +++--- qapi/block-export.json | 2 +- qapi/block.json | 2 +- qapi/control.json | 5 ++--- qapi/dump.json | 5 ++--- qapi/introspect.json | 6 +++--- qapi/job.json | 2 +- qapi/machine-target.json | 7 +++---- qapi/misc-target.json | 2 +- qapi/misc.json | 5 ++--- qapi/net.json | 2 +- qapi/pci.json | 2 +- qapi/qdev.json | 3 +-- qapi/qom.json | 8 +++----- qapi/stats.json | 2 +- qapi/trace.json | 2 +- qapi/ui.json | 2 +- qapi/virtio.json | 6 +++--- 18 files changed, 31 insertions(+), 38 deletions(-)