qapi: add auto-generated return docs
v6 cover qapi: add auto-generated return docs
This series adds the ability for the new QAPIDoc system to generate "Returns:" documentation based on the return type declared in the Schema even when no explicit documentation is found in the QAPI source. As a result and as an immediate cleanup, trivial return statements are removed and remaining Return documentation is revised to avoid re-stating the return type, which is always generated automatically.
v6: ... actually read Markus' algorithm and then did that.
Added a few TODO: separators to improve placement
Still kind of wonky: The reason x-debug-block-dirty-bitmap-sha256 appears to generate oddly is because the "Arguments:" section is *also* being generated, and it occurs *after* parsing and schema generation, entirely within the doc generator. Mea Culpa: can we address this later?
v5: rebased, implemented Markus' preferred insertion algorithm
v4: rebased on origin/master (2025-06-12)
v3: rebased on top of python-qapi-linting (v4) pull request;
removed commits that are no longer needed.
v2: fix multi-return-sections bug :(
John Snow (4):
docs/qapi-domain: add return-nodesc
docs, qapi: generate undocumented return sections
qapi: remove trivial "Returns:" sections
qapi: rephrase return docs to avoid type name
docs/devel/qapi-domain.rst | 30 ++++++++++++++++++++++++++++++ docs/sphinx/qapi_domain.py | 8 ++++++++ docs/sphinx/qapidoc.py | 14 ++++++++------ qapi/audio.json | 2 -- qapi/block-core.json | 14 +++----------- qapi/block-export.json | 2 +- qapi/block.json | 2 +- qapi/char.json | 8 -------- qapi/control.json | 5 ++--- qapi/cryptodev.json | 2 -- qapi/dump.json | 5 ++--- qapi/introspect.json | 6 +++--- qapi/job.json | 2 +- qapi/machine.json | 24 ++---------------------- qapi/migration.json | 12 ++---------- qapi/misc-i386.json | 12 +----------- qapi/misc.json | 12 ++---------- qapi/net.json | 2 +- qapi/pci.json | 2 +- qapi/qdev.json | 3 +-- qapi/qom.json | 8 +++----- qapi/rocker.json | 4 ---- qapi/run-state.json | 2 -- qapi/stats.json | 2 +- qapi/tpm.json | 4 ---- qapi/trace.json | 2 +- qapi/ui.json | 10 +--------- qapi/virtio.json | 8 +++----- qapi/yank.json | 2 +- scripts/qapi/parser.py | 35 +++++++++++++++++++++++++++++++++++ scripts/qapi/schema.py | 3 +++ 31 files changed, 117 insertions(+), 130 deletions(-)
Signature · 1 line
2.50.0
PATCH v6 2/4 docs, qapi: generate undocumented return sections
This patch changes the qapidoc parser to generate stub Return value documentation for any command that has a return value but does not have a "Returns:" doc section.
The stubs include just the type name, which will be rendered with a cross-reference link in the HTML output.
The algorithm for where return sections are placed is as follows:
1. If we have arguments, return goes right after them.
2. Else if we have errors, return goes right before them.
3. Else if we have features, return goes right before them.
4. Else return goes right after the intro
To facilitate this algorithm, a "TODO:" hack line is used to separate the intro from the remainder of the documentation block in cases where there are no other sections to separate the intro from e.g. examples and additional detail meant to appear below the key sections of interest.
--- docs/sphinx/qapidoc.py | 14 ++++++++------ qapi/machine.json | 2 ++ scripts/qapi/parser.py | 35 +++++++++++++++++++++++++++++++++++ scripts/qapi/schema.py | 3 +++ 4 files changed, 48 insertions(+), 6 deletions(-)
docs/sphinx/qapidoc.py +8 -6
@@ -255,16 +255,18 @@ def visit_feature(self, section: QAPIDoc.ArgSection) -> None: def visit_returns(self, section: QAPIDoc.Section) -> None: assert isinstance(self.entity, QAPISchemaCommand) rtype = self.entity.ret_type - # q_empty can produce None, but we won't be documenting anything - # without an explicit return statement in the doc block, and we - # should not have any such explicit statements when there is no - # return value. + # return statements will not be present (and won't be + # autogenerated) for any command that doesn't return + # *something*, so rtype will always be defined here. assert rtype typ = self.format_type(rtype) assert typ - assert section.text - self.add_field("return", typ, section.text, section.info) + + if section.text: + self.add_field("return", typ, section.text, section.info) + else: + self.add_lines(f":return-nodesc: {typ}", section.info) def visit_errors(self, section: QAPIDoc.Section) -> None: # FIXME: the formatting for errors may be inconsistent and may
qapi/machine.json +2 -0
@@ -1301,6 +1301,8 @@ # Return the amount of initially allocated and present hotpluggable # (if enabled) memory in bytes. # +# TODO: This line is a hack to separate the example from the body +# # .. qmp-example:: # # -> { "execute": "query-memory-size-summary" }
scripts/qapi/parser.py +35 -0
@@ -815,6 +815,41 @@ def connect_feature(self, feature: 'QAPISchemaFeature') -> None: % feature.name) self.features[feature.name].connect(feature) + def ensure_returns(self, info: QAPISourceInfo) -> None: + + def _insert_near_kind( + kind: QAPIDoc.Kind, + new_sect: QAPIDoc.Section, + after: bool = False, + ) -> bool: + for sect in filter(lambda sect: sect.kind == kind, reversed( + self.all_sections)): + idx = self.all_sections.index(sect) + (1 if after else 0) + self.all_sections.insert(idx, new_sect) + return True + return False + + if any(s.kind == QAPIDoc.Kind.RETURNS for s in self.all_sections): + return + + # Stub "Returns" section for undocumented returns value + stub = QAPIDoc.Section(info, QAPIDoc.Kind.RETURNS) + + if any(_insert_near_kind(kind, stub, after) for kind, after in ( + # 1. If arguments, right after those. + (QAPIDoc.Kind.MEMBER, True), + # 2. Elif errors, right *before* those. + (QAPIDoc.Kind.ERRORS, False), + # 3. Elif features, right *before* those. + (QAPIDoc.Kind.FEATURE, False), + )): + return + + # Otherwise, it should go right after the intro. The intro + # is always the first section and is always present (even + # when empty), so we can insert directly at index=1 blindly. + self.all_sections.insert(1, stub) + def check_expr(self, expr: QAPIExpression) -> None: if 'command' in expr: if self.returns and 'returns' not in expr:
scripts/qapi/schema.py +3 -0
@@ -1062,6 +1062,9 @@ def connect_doc(self, doc: Optional[QAPIDoc] = None) -> None: if self.arg_type and self.arg_type.is_implicit(): self.arg_type.connect_doc(doc) + if self.ret_type and self.info: + doc.ensure_returns(self.info) + def visit(self, visitor: QAPISchemaVisitor) -> None: super().visit(visitor) visitor.visit_command(
Signature · 1 line
2.50.0
PATCH v6 1/4 docs/qapi-domain: add return-nodesc
In reply to John SnowThis form is used to annotate a return type without an accompanying description, for when there is no "Returns:" information in the source doc, but we have a return type we want to generate a cross-reference to.
The syntax is:
:return-nodesc: TypeName
It's primarily necessary because Sphinx always expects both a type and a description for the prior form and will format it accordingly. To have a reasonable rendering when the body is missing, we need to use a different info field list entirely.
--- docs/devel/qapi-domain.rst | 30 ++++++++++++++++++++++++++++++ docs/sphinx/qapi_domain.py | 8 ++++++++ 2 files changed, 38 insertions(+)
docs/devel/qapi-domain.rst +30 -0
@@ -242,6 +242,36 @@ Example:: } +``:return-nodesc:`` +------------------- + +Document the return type of a QAPI command, without an accompanying description. + +:availability: This field list is only available in the body of the + Command directive. +:syntax: ``:return-nodesc: type`` +:type: `sphinx.util.docfields.Field + <https://pydoc.dev/sphinx/latest/sphinx.util.docfields.Field.html?private=1>`_ + + +Example:: + + .. qapi:command:: query-replay + :since: 5.2 + + Retrieve the record/replay information. It includes current + instruction count which may be used for ``replay-break`` and + ``replay-seek`` commands. + + :return-nodesc: ReplayInfo + + .. qmp-example:: + + -> { "execute": "query-replay" } + <- { "return": { + "mode": "play", "filename": "log.rr", "icount": 220414 } + } + ``:value:`` -----------
docs/sphinx/qapi_domain.py +8 -0
@@ -532,6 +532,14 @@ class QAPICommand(QAPIObject): names=("return",), can_collapse=True, ), + # :return-nodesc: TypeName + CompatField( + "returnvalue", + label=_("Return"), + names=("return-nodesc",), + bodyrolename="type", + has_arg=False, + ), ] )
Signature · 1 line
2.50.0
PATCH v6 4/4 qapi: rephrase return docs to avoid type name
In reply to John SnowWell, I tried. Maybe not very hard. Sorry!
--- 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/misc-i386.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 +++--- 17 files changed, 28 insertions(+), 34 deletions(-)
qapi/block-core.json +3 -3
@@ -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 ##
qapi/block-export.json +1 -1
@@ -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 ##
qapi/block.json +1 -1
@@ -86,7 +86,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
qapi/control.json +2 -3
@@ -93,8 +93,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 #
@@ -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 #
qapi/dump.json +2 -3
@@ -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 @@ # # 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 #
qapi/introspect.json +3 -3
@@ -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). #
qapi/job.json +1 -1
@@ -295,7 +295,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 ##
qapi/misc-i386.json +1 -1
@@ -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
qapi/misc.json +2 -3
@@ -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
qapi/net.json +1 -1
@@ -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
qapi/pci.json +1 -1
@@ -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.
qapi/qdev.json +1 -2
@@ -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
qapi/qom.json +3 -5
@@ -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 ##
qapi/stats.json +1 -1
@@ -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
qapi/trace.json +1 -1
@@ -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 #
qapi/ui.json +1 -1
@@ -816,7 +816,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 #
qapi/virtio.json +3 -3
@@ -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 #
Signature · 1 line
2.50.0
PATCH v6 3/4 qapi: remove trivial "Returns:" sections
In reply to John SnowThe 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, several doc blocks have a "TODO:" line inserted to help the placement algorithm differentiate the introductory paragraph(s) from the rest of the documentation.
--- qapi/audio.json | 2 -- qapi/block-core.json | 8 -------- qapi/char.json | 8 -------- qapi/cryptodev.json | 2 -- qapi/machine.json | 22 ---------------------- qapi/migration.json | 12 ++---------- qapi/misc-i386.json | 10 ---------- qapi/misc.json | 7 ------- qapi/rocker.json | 4 ---- qapi/run-state.json | 2 -- qapi/tpm.json | 4 ---- qapi/ui.json | 8 -------- qapi/virtio.json | 2 -- qapi/yank.json | 2 +- 14 files changed, 3 insertions(+), 90 deletions(-)
qapi/audio.json +0 -2
@@ -535,8 +535,6 @@ # # Return information about audiodev configuration # -# Returns: array of @Audiodev -# # Since: 8.0 ## { 'command': 'query-audiodevs',
qapi/block-core.json +0 -8
@@ -1950,8 +1950,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::
@@ -2464,9 +2462,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
@@ -6202,9 +6197,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
qapi/char.json +0 -8
@@ -36,8 +36,6 @@ # # Return information about current character devices. # -# Returns: a list of @ChardevInfo -# # Since: 0.14 # # .. qmp-example::
@@ -82,8 +80,6 @@ # # Return information about character device backends. # -# Returns: a list of @ChardevBackendInfo -# # Since: 2.0 # # .. qmp-example::
@@ -772,8 +768,6 @@ # # @backend: backend type and parameters # -# Returns: ChardevReturn. -# # Since: 1.4 # # .. qmp-example::
@@ -812,8 +806,6 @@ # # @backend: new backend type and parameters # -# Returns: ChardevReturn. -# # Since: 2.10 # # .. qmp-example::
qapi/cryptodev.json +0 -2
@@ -96,8 +96,6 @@ # # Return information about current crypto devices. # -# Returns: a list of @QCryptodevInfo -# # Since: 8.0 ## { 'command': 'query-cryptodev', 'returns': ['QCryptodevInfo']}
qapi/machine.json +0 -22
@@ -101,8 +101,6 @@ # # Return information about all virtual CPUs. # -# Returns: list of @CpuInfoFast -# # Since: 2.12 # # .. qmp-example::
@@ -218,8 +216,6 @@ # # @unstable: Argument @compat-props is experimental. # -# Returns: a list of MachineInfo -# # Since: 1.2 # # .. qmp-example::
@@ -268,8 +264,6 @@ # # Return information on the current virtual machine. # -# Returns: CurrentMachineParams -# # Since: 4.0 ## { 'command': 'query-current-machine', 'returns': 'CurrentMachineParams' }
@@ -291,8 +285,6 @@ # # Return information about the target for this QEMU # -# Returns: QemuTargetInfo -# # Since: 1.2 ## { 'command': 'query-target', 'returns': 'QemuTargetInfo' }
@@ -316,8 +308,6 @@ # # Query the guest UUID information. # -# Returns: The @UuidInfo for the guest -# # Since: 0.14 # # .. qmp-example::
@@ -469,8 +459,6 @@ # # Return information about KVM acceleration # -# Returns: @KvmInfo -# # Since: 0.14 # # .. qmp-example::
@@ -932,8 +920,6 @@ # # Return information for all memory backends. # -# Returns: a list of @Memdev. -# # Since: 2.1 # # .. qmp-example::
@@ -1049,8 +1035,6 @@ # # TODO: Better documentation; currently there is none. # -# Returns: a list of HotpluggableCPU objects. -# # Since: 2.7 # # .. qmp-example::
@@ -1172,9 +1156,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
@@ -1238,9 +1219,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
qapi/migration.json +2 -10
@@ -286,8 +286,6 @@ # is active there will be another json-object with RAM migration # status. # -# Returns: @MigrationInfo -# # Since: 0.14 # # .. qmp-example::
@@ -537,8 +535,6 @@ # # Return information about the current migration capabilities status # -# Returns: @MigrationCapabilityStatus -# # Since: 1.2 # # .. qmp-example::
@@ -1324,8 +1320,6 @@ # # Return information about the current migration parameters # -# Returns: @MigrationParameters -# # Since: 2.4 # # .. qmp-example::
@@ -1906,7 +1900,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:: #
@@ -1960,7 +1954,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:: #
@@ -2335,8 +2329,6 @@ # # @deprecated: This command is deprecated with no replacement yet. # -# Returns: @MigrationThreadInfo -# # Since: 7.2 ## { 'command': 'query-migrationthreads',
qapi/misc-i386.json +0 -10
@@ -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 #
@@ -281,8 +277,6 @@ # @mnonce: a random 16 bytes value encoded in base64 (it will be # included in report) # -# Returns: SevAttestationReport objects. -# # Errors: # - This will return an error if the attestation report is # unavailable, either due to an invalid guest configuration
@@ -345,8 +339,6 @@ # # Return information about configured SGX capabilities of guest # -# Returns: @SgxInfo -# # Since: 6.2 # # .. qmp-example::
@@ -364,8 +356,6 @@ # # Return information about SGX capabilities of host # -# Returns: @SgxInfo -# # Since: 6.2 # # .. qmp-example::
qapi/misc.json +0 -7
@@ -56,8 +56,6 @@ # # Return the name information of a guest. # -# Returns: @NameInfo of the guest -# # Since: 0.14 # # .. qmp-example::
@@ -332,9 +330,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
@@ -415,8 +410,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.
qapi/rocker.json +0 -4
@@ -28,8 +28,6 @@ # # @name: switch name # -# Returns: @Rocker information -# # Since: 2.4 # # .. qmp-example::
@@ -98,8 +96,6 @@ # # @name: port name # -# Returns: a list of @RockerPort information -# # Since: 2.4 # # .. qmp-example::
qapi/run-state.json +0 -2
@@ -119,8 +119,6 @@ # # Query the run status of the VM # -# Returns: @StatusInfo reflecting the VM -# # Since: 0.14 # # .. qmp-example::
qapi/tpm.json +0 -4
@@ -27,8 +27,6 @@ # # Return a list of supported TPM models # -# Returns: a list of TpmModel -# # Since: 1.5 # # .. qmp-example::
@@ -58,8 +56,6 @@ # # Return a list of supported TPM types # -# Returns: a list of TpmType -# # Since: 1.5 # # .. qmp-example::
qapi/ui.json +0 -8
@@ -325,8 +325,6 @@ # # Return information about the current SPICE server # -# Returns: @SpiceInfo -# # Since: 0.14 # # .. qmp-example::
@@ -656,8 +654,6 @@ # # Return information about the current VNC server # -# Returns: @VncInfo -# # Since: 0.14 # # .. qmp-example::
@@ -687,8 +683,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'],
@@ -1564,8 +1558,6 @@ # # Return information about display configuration # -# Returns: @DisplayOptions -# # Since: 3.1 ## { 'command': 'query-display-options',
qapi/virtio.json +0 -2
@@ -847,8 +847,6 @@ # # @unstable: This command is meant for debugging. # -# Returns: VirtioQueueElement information -# # Since: 7.2 # # .. qmp-example::
qapi/yank.json +1 -1
@@ -102,7 +102,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:: #
Signature · 1 line
2.50.0
Re: [PATCH v6 2/4] docs, qapi: generate undocumented return sections
In reply to John SnowQuoted 14 lines · John Snow
This patch changes the qapidoc parser to generate stub Return value documentation for any command that has a return value but does not have a "Returns:" doc section.
The stubs include just the type name, which will be rendered with a cross-reference link in the HTML output.
The algorithm for where return sections are placed is as follows:
1. If we have arguments, return goes right after them.
2. Else if we have errors, return goes right before them.
3. Else if we have features, return goes right before them.
4. Else return goes right after the intro
Quoted 4 lines
To facilitate this algorithm, a "TODO:" hack line is used to separate the intro from the remainder of the documentation block in cases where there are no other sections to separate the intro from e.g. examples and additional detail meant to appear below the key sections of interest.
Good, except it neglects to spell out *why* we do this. Here's my attempt:
qapi: Fix undocumented return values by generating something
Generated command documentation lacks information on return value in several cases, e.g. query-tpm.
The obvious fix would be to require a Returns: section when a command returns something.
However, note that many existing Returns: sections are pretty useless:
the description is basically the return type, which then gets rendered like "Return: <Type> – <basically the return type>". This suggests that a description is often not really necessary, and requiring one isn't useful.
Instead, generate the obvious minimal thing when Returns: is absent:
"Return: <Type>".
This auto-generated Return documentation is placed is as follows:
Quoted 62 lines
Signed-off-by John Snow <[email protected]>--- docs/sphinx/qapidoc.py | 14 ++++++++------ qapi/machine.json | 2 ++ scripts/qapi/parser.py | 35 +++++++++++++++++++++++++++++++++++ scripts/qapi/schema.py | 3 +++ 4 files changed, 48 insertions(+), 6 deletions(-)docs/sphinx/qapidoc.py +8
-6@@ -255,16 +255,18 @@ def visit_feature(self, section: QAPIDoc.ArgSection) -> None: def visit_returns(self, section: QAPIDoc.Section) -> None: assert isinstance(self.entity, QAPISchemaCommand) rtype = self.entity.ret_type - # q_empty can produce None, but we won't be documenting anything - # without an explicit return statement in the doc block, and we - # should not have any such explicit statements when there is no - # return value. + # return statements will not be present (and won't be + # autogenerated) for any command that doesn't return + # *something*, so rtype will always be defined here. assert rtype typ = self.format_type(rtype) assert typ - assert section.text - self.add_field("return", typ, section.text, section.info) + + if section.text: + self.add_field("return", typ, section.text, section.info) + else: + self.add_lines(f":return-nodesc: {typ}", section.info) def visit_errors(self, section: QAPIDoc.Section) -> None: # FIXME: the formatting for errors may be inconsistent and mayqapi/machine.json +2
-0@@ -1301,6 +1301,8 @@ # Return the amount of initially allocated and present hotpluggable # (if enabled) memory in bytes. # +# TODO: This line is a hack to separate the example from the body +# # .. qmp-example:: # # -> { "execute": "query-memory-size-summary" }scripts/qapi/parser.py +3
-0@@ -815,6 +815,41 @@ def connect_feature(self, feature: 'QAPISchemaFeature') -> None: % feature.name) self.features[feature.name].connect(feature) + def ensure_returns(self, info: QAPISourceInfo) -> None: + + def _insert_near_kind(
scripts/qapi/parser.py def connect_feature(self, feature: 'QAPISchemaFeature') -> None: · line 830
Quoted 10 lines
scripts/qapi/parser.py +10
-0+ kind: QAPIDoc.Kind, + new_sect: QAPIDoc.Section, + after: bool = False, + ) -> bool: + for sect in filter(lambda sect: sect.kind == kind, reversed( + self.all_sections)): + idx = self.all_sections.index(sect) + (1 if after else 0) + self.all_sections.insert(idx, new_sect) + return True + return False
I find this function a bit hard to understand.
filter() returns an iterator for the sections of kind @kind in @all_sections.
The for loop doesn't actually loop, it executes its body at most once.
If there are no sections of kind @kind, it doesn't execute the body, and returns False.
If there are such sections, the body is executed for the first one, i.e. the last section of kind @kind in @all_sections. It then searches @all_sections again to find its index, inserts the new section before or after that index, and returns True.
Here's my attempt to write less clever code:
def _insert_near_kind(
kind: QAPIDoc.Kind,
new_sect: QAPIDoc.Section,
after: bool = False,
) -> bool:
for idx, sect in enumerate(reversed(self.all_sections)):
if sect.kind == kind:
pos = len(self.all_sections) - idx - 1
if after:
pos += 1
self.all_sections.insert(pos, new_sect)
return True
return FalseWhat do you think?
Quoted 30 lines
scripts/qapi/parser.py +22
-0+ + if any(s.kind == QAPIDoc.Kind.RETURNS for s in self.all_sections): + return + + # Stub "Returns" section for undocumented returns value + stub = QAPIDoc.Section(info, QAPIDoc.Kind.RETURNS) + + if any(_insert_near_kind(kind, stub, after) for kind, after in ( + # 1. If arguments, right after those. + (QAPIDoc.Kind.MEMBER, True), + # 2. Elif errors, right *before* those. + (QAPIDoc.Kind.ERRORS, False), + # 3. Elif features, right *before* those. + (QAPIDoc.Kind.FEATURE, False), + )): + return + + # Otherwise, it should go right after the intro. The intro + # is always the first section and is always present (even + # when empty), so we can insert directly at index=1 blindly. + self.all_sections.insert(1, stub) + def check_expr(self, expr: QAPIExpression) -> None: if 'command' in expr: if self.returns and 'returns' not in expr:scripts/qapi/schema.py +0
-0
scripts/qapi/schema.py def connect_doc(self, doc: Optional[QAPIDoc] = None) -> None: · line 1070
Quoted 9 lines
scripts/qapi/schema.py +3
-0@@ -1062,6 +1062,9 @@ def connect_doc(self, doc: Optional[QAPIDoc] = None) -> None: if self.arg_type and self.arg_type.is_implicit(): self.arg_type.connect_doc(doc) + if self.ret_type and self.info: + doc.ensure_returns(self.info) + def visit(self, visitor: QAPISchemaVisitor) -> None: super().visit(visitor) visitor.visit_command(
Let's check how generated output changes:
diff -rup 01-qapi-gen-1711c67f7c/qemu-qmp-ref.txt 02-qapi-gen-cfb5bf6462/qemu-qmp-ref.txt
--- 01-qapi-gen-1711c67f7c/qemu-qmp-ref.txt 2025-07-11 11:38:27.142499312 +0200
+++ 02-qapi-gen-cfb5bf6462/qemu-qmp-ref.txt 2025-07-11 11:41:35.193205635 +0200
@@ -3607,6 +3607,9 @@ Command x-debug-query-block-graph (Since
Get the block graph.
+ Return:
+ "XDbgBlockGraph"
+
Clause 3. Else if we have features, return goes right before them. Good.
Features:
* **unstable** -- This command is meant for debugging.
@@ -10350,6 +10353,9 @@ Command query-tpm (Since: 1.5)
Return information about the TPM device
+ Return:
+ "[""TPMInfo""]"
+
Clause 4. Else return goes right after the intro. Good.
Note: schema source terminates intro with Since: section.
Example::
-> { "execute": "query-tpm" } @@ -13991,6 +13997,9 @@ Command query-dirty-rate (Since: 5.2)
which to report calculation time. By default it is reported in seconds. (Since 8.2)
+ Return:
+ "DirtyRateInfo"
+
Clause 1. If we have arguments, return goes right after them. Good.
Example: Measurement is in progress:
<- {"status": "measuring", "sample-pages": 512,
@@ -14061,6 +14070,9 @@ Command query-vcpu-dirty-limit (Since: 7
Return information about virtual CPU dirty page rate limits, if any.
+ Return:
+ "[""DirtyLimitInfo""]"
+
Clause 4. Else return goes right after the intro. Good.
Example::
-> {"execute": "query-vcpu-dirty-limit"}@@ -16775,6 +16787,9 @@ Command query-vm-generation-id (Since: 2
Show Virtual Machine Generation ID
+ Return:
+ "GuidInfo"
+
Clause 4. Else return goes right after the intro. Good.
Command system_reset (Since: 0.14)
Performs a hard reset of a guest.
@@ -17548,6 +17563,9 @@ Command query-memory-size-summary (Since
Return the amount of initially allocated and present hotpluggable (if enabled) memory in bytes.
+ Return:
+ "MemoryInfo"
+
Clause 4. Else return goes right after the intro. Good.
Example::
-> { "execute": "query-memory-size-summary" }@@ -17739,6 +17757,9 @@ Command query-memory-devices (Since: 2.1
Lists available memory devices and their state
+ Return:
+ "[""MemoryDeviceInfo""]"
+
Clause 4. Else return goes right after the intro. Good.
Example::
-> { "execute": "query-memory-devices" } @@ -20012,6 +20033,9 @@ Command query-acpi-ospm-status (Since: 2
Return a list of ACPIOSTInfo for devices that support status reporting via ACPI _OST method.
+ Return:
+ "[""ACPIOSTInfo""]"
+
Clause 4. Else return goes right after the intro. Good.
Example::
-> { "execute": "query-acpi-ospm-status" } @@ -20498,6 +20522,9 @@ Command query-stats-schemas (Since: 7.1)
* **provider** ("StatsProvider", *optional*) -- a provider to restrict the query to.
+ Return:
+ "[""StatsSchema""]"
+
Clause 1. If we have arguments, return goes right after them. Good.
Note:
Runtime-collected statistics and their names fall outside QEMU's
Placement is all good.
Clauses 1, 3, 4 covered. The next patch will cover clause 2.
In all instances of clause 4 but one, intro is terminated by a Since:
section.
The exception is query-memory-size-summary, which has its Since: at the end. It therefore needs the "TODO:" hack line you add to separate intro from example.
All but one of the intro-terminating Since: are followed by an example. We more commonly put Since: at the very end (roughly 3 out of four times). But if we moved these to the end, we'd need a "TODO:" hack line to separate intro from example.
The need for terminating the intro is not obvious when writing doc comments. Mistakes are bound to happen.
I understand the inliner similarly relies on intro-termination for placement.
We've toyed with the idea of automating since information. If we pull that off, the Since: go away.
I think relying on existing Since: for separation is fine for now, but we'll likely need a more robust solution eventually.
With the commit message amended and preferably with a less clever version of _insert_near_kind():
Re: [PATCH v6 3/4] qapi: remove trivial "Returns:" sections
In reply to John SnowQuoted 5 lines · John Snow
The new
qapidoc.pycan 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.
Quoted 8 lines
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, several doc blocks have a "TODO:" line inserted to help the placement algorithm differentiate the introductory paragraph(s) from the rest of the documentation.
Just three out of 44, fortunately. I discussed this further in review of the previous patch.
Three others move, as we'll see below. The commit message could mention it. We could also do the moves in a separate patch. Let's do commit message, it's easier. Perhaps:
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.
Quoted 468 lines
Signed-off-by John Snow <[email protected]>--- qapi/audio.json | 2 -- qapi/block-core.json | 8 -------- qapi/char.json | 8 -------- qapi/cryptodev.json | 2 -- qapi/machine.json | 22 ---------------------- qapi/migration.json | 12 ++---------- qapi/misc-i386.json | 10 ---------- qapi/misc.json | 7 ------- qapi/rocker.json | 4 ---- qapi/run-state.json | 2 -- qapi/tpm.json | 4 ---- qapi/ui.json | 8 -------- qapi/virtio.json | 2 -- qapi/yank.json | 2 +- 14 files changed, 3 insertions(+), 90 deletions(-)qapi/audio.json +0
-2@@ -535,8 +535,6 @@ # # Return information about audiodev configuration # -# Returns: array of @Audiodev -# # Since: 8.0 ## { 'command': 'query-audiodevs',qapi/block-core.json +0
-8@@ -1950,8 +1950,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::@@ -2464,9 +2462,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@@ -6202,9 +6197,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, GenericErrorqapi/char.json +0
-8@@ -36,8 +36,6 @@ # # Return information about current character devices. # -# Returns: a list of @ChardevInfo -# # Since: 0.14 # # .. qmp-example::@@ -82,8 +80,6 @@ # # Return information about character device backends. # -# Returns: a list of @ChardevBackendInfo -# # Since: 2.0 # # .. qmp-example::@@ -772,8 +768,6 @@ # # @backend: backend type and parameters # -# Returns: ChardevReturn. -# # Since: 1.4 # # .. qmp-example::@@ -812,8 +806,6 @@ # # @backend: new backend type and parameters # -# Returns: ChardevReturn. -# # Since: 2.10 # # .. qmp-example::qapi/cryptodev.json +0
-2@@ -96,8 +96,6 @@ # # Return information about current crypto devices. # -# Returns: a list of @QCryptodevInfo -# # Since: 8.0 ## { 'command': 'query-cryptodev', 'returns': ['QCryptodevInfo']}qapi/machine.json +0
-22@@ -101,8 +101,6 @@ # # Return information about all virtual CPUs. # -# Returns: list of @CpuInfoFast -# # Since: 2.12 # # .. qmp-example::@@ -218,8 +216,6 @@ # # @unstable: Argument @compat-props is experimental. # -# Returns: a list of MachineInfo -# # Since: 1.2 # # .. qmp-example::@@ -268,8 +264,6 @@ # # Return information on the current virtual machine. # -# Returns: CurrentMachineParams -# # Since: 4.0 ## { 'command': 'query-current-machine', 'returns': 'CurrentMachineParams' }@@ -291,8 +285,6 @@ # # Return information about the target for this QEMU # -# Returns: QemuTargetInfo -# # Since: 1.2 ## { 'command': 'query-target', 'returns': 'QemuTargetInfo' }@@ -316,8 +308,6 @@ # # Query the guest UUID information. # -# Returns: The @UuidInfo for the guest -# # Since: 0.14 # # .. qmp-example::@@ -469,8 +459,6 @@ # # Return information about KVM acceleration # -# Returns: @KvmInfo -# # Since: 0.14 # # .. qmp-example::@@ -932,8 +920,6 @@ # # Return information for all memory backends. # -# Returns: a list of @Memdev. -# # Since: 2.1 # # .. qmp-example::@@ -1049,8 +1035,6 @@ # # TODO: Better documentation; currently there is none. # -# Returns: a list of HotpluggableCPU objects. -# # Since: 2.7 # # .. qmp-example::@@ -1172,9 +1156,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@@ -1238,9 +1219,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 reportqapi/migration.json +2
-10@@ -286,8 +286,6 @@ # is active there will be another json-object with RAM migration # status. # -# Returns: @MigrationInfo -# # Since: 0.14 # # .. qmp-example::@@ -537,8 +535,6 @@ # # Return information about the current migration capabilities status # -# Returns: @MigrationCapabilityStatus -# # Since: 1.2 # # .. qmp-example::@@ -1324,8 +1320,6 @@ # # Return information about the current migration parameters # -# Returns: @MigrationParameters -# # Since: 2.4 # # .. qmp-example::@@ -1906,7 +1900,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:: #@@ -1960,7 +1954,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:: #@@ -2335,8 +2329,6 @@ # # @deprecated: This command is deprecated with no replacement yet. # -# Returns: @MigrationThreadInfo -# # Since: 7.2 ## { 'command': 'query-migrationthreads',qapi/misc-i386.json +0
-10@@ -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 #@@ -281,8 +277,6 @@ # @mnonce: a random 16 bytes value encoded in base64 (it will be # included in report) # -# Returns: SevAttestationReport objects. -# # Errors: # - This will return an error if the attestation report is # unavailable, either due to an invalid guest configuration@@ -345,8 +339,6 @@ # # Return information about configured SGX capabilities of guest # -# Returns: @SgxInfo -# # Since: 6.2 # # .. qmp-example::@@ -364,8 +356,6 @@ # # Return information about SGX capabilities of host # -# Returns: @SgxInfo -# # Since: 6.2 # # .. qmp-example::qapi/misc.json +0
-7@@ -56,8 +56,6 @@ # # Return the name information of a guest. # -# Returns: @NameInfo of the guest -# # Since: 0.14 # # .. qmp-example::@@ -332,9 +330,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@@ -415,8 +410,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.qapi/rocker.json +0
-4@@ -28,8 +28,6 @@ # # @name: switch name # -# Returns: @Rocker information -# # Since: 2.4 # # .. qmp-example::@@ -98,8 +96,6 @@ # # @name: port name # -# Returns: a list of @RockerPort information -# # Since: 2.4 # # .. qmp-example::qapi/run-state.json +0
-2@@ -119,8 +119,6 @@ # # Query the run status of the VM # -# Returns: @StatusInfo reflecting the VM -# # Since: 0.14 # # .. qmp-example::qapi/tpm.json +0
-4@@ -27,8 +27,6 @@ # # Return a list of supported TPM models # -# Returns: a list of TpmModel -# # Since: 1.5 # # .. qmp-example::@@ -58,8 +56,6 @@ # # Return a list of supported TPM types # -# Returns: a list of TpmType -# # Since: 1.5 # # .. qmp-example::qapi/ui.json +0
-8@@ -325,8 +325,6 @@ # # Return information about the current SPICE server # -# Returns: @SpiceInfo -# # Since: 0.14 # # .. qmp-example::@@ -656,8 +654,6 @@ # # Return information about the current VNC server # -# Returns: @VncInfo -# # Since: 0.14 # # .. qmp-example::@@ -687,8 +683,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'],@@ -1564,8 +1558,6 @@ # # Return information about display configuration # -# Returns: @DisplayOptions -# # Since: 3.1 ## { 'command': 'query-display-options',qapi/virtio.json +0
-2@@ -847,8 +847,6 @@ # # @unstable: This command is meant for debugging. # -# Returns: VirtioQueueElement information -# # Since: 7.2 # # .. qmp-example::qapi/yank.json +0
-0
qapi/yank.json line 108
Quoted 8 lines
qapi/yank.json +1
-1@@ -102,7 +102,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:: #
Let's check how generated output changes:
@@ -591,7 +591,7 @@ Command query-status (Since: 0.14)
Query the run status of the VM
Return:
- "StatusInfo" -- "StatusInfo" reflecting the VM
+ "StatusInfo"
Expected loss of redundant description text. Good. Not commenting on this again.
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -3473,7 +3473,7 @@ Command query-named-block-nodes (Since:
(Since 5.0)
Return: - "[""BlockDeviceInfo""]" -- the list of BlockDeviceInfo
+ "[""BlockDeviceInfo""]"
Clause 1. If we have arguments, return goes right after them. Good.
Example::
@@ -3919,7 +3919,7 @@ Command x-debug-block-dirty-bitmap-sha25
* **unstable** -- This command is meant for debugging.
Return:
- "BlockDirtyBitmapSha256" -- BlockDirtyBitmapSha256
+ "BlockDirtyBitmapSha256"
Clause 1. If we have arguments, return goes right after them. Good.
Errors:
* If "node" is not a valid block device, DeviceNotFound
@@ -7200,7 +7200,7 @@ Command blockdev-snapshot-delete-interna
name to be deleted
Return:
- "SnapshotInfo" -- SnapshotInfo
+ "SnapshotInfo"
Clause 1. If we have arguments, return goes right after them. Good.
Errors:
* If "device" is not a valid block device, GenericError
@@ -8146,7 +8146,7 @@ Command query-chardev (Since: 0.14)
Return information about current character devices.
Return:
- "[""ChardevInfo""]" -- a list of "ChardevInfo"
+ "[""ChardevInfo""]"
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -8183,7 +8183,7 @@ Command query-chardev-backends (Since: 2
Return information about character device backends.
Return:
- "[""ChardevBackendInfo""]" -- a list of "ChardevBackendInfo"
+ "[""ChardevBackendInfo""]"
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -8724,7 +8724,7 @@ Command chardev-add (Since: 1.4)
* **backend** ("ChardevBackend") -- backend type and parameters
Return:
- "ChardevReturn" -- ChardevReturn.
+ "ChardevReturn"
Clause 1. If we have arguments, return goes right after them. Good.
Example::
@@ -8759,7 +8759,7 @@ Command chardev-change (Since: 2.10)
parameters
Return:
- "ChardevReturn" -- ChardevReturn.
+ "ChardevReturn"
Clause 1. If we have arguments, return goes right after them. Good.
Example::
@@ -9970,7 +9970,7 @@ Command query-rocker (Since: 2.4)
* **name** ("string") -- switch name
Return:
- "RockerSwitch" -- "Rocker" information
+ "RockerSwitch"
Clause 1. If we have arguments, return goes right after them. Good.
Example::
@@ -10020,7 +10020,7 @@ Command query-rocker-ports (Since: 2.4)
* **name** ("string") -- port name
Return:
- "[""RockerPort""]" -- a list of "RockerPort" information
+ "[""RockerPort""]"
Clause 1. If we have arguments, return goes right after them. Good.
Example::
@@ -10249,7 +10249,7 @@ Command query-tpm-models (Since: 1.5)
Return a list of supported TPM models
Return:
- "[""TpmModel""]" -- a list of TpmModel
+ "[""TpmModel""]"
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -10272,7 +10272,7 @@ Command query-tpm-types (Since: 1.5)
Return a list of supported TPM types
Return:
- "[""TpmType""]" -- a list of TpmType
+ "[""TpmType""]"
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -10652,7 +10652,7 @@ Command query-spice (Since: 0.14)
Return information about the current SPICE server
Return:
- "SpiceInfo" -- "SpiceInfo"
+ "SpiceInfo"
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -10969,7 +10969,7 @@ Command query-vnc (Since: 0.14)
Return information about the current VNC server
Return:
- "VncInfo" -- "VncInfo"
+ "VncInfo"
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -10997,7 +10997,7 @@ Command query-vnc-servers (Since: 2.3)
Return a list of vnc servers. The list can be empty.
Return:
- "[""VncInfo2""]" -- a list of "VncInfo2"
+ "[""VncInfo2""]"
Clause 4. Else return goes right after the intro. Good.
Command change-vnc-password (Since: 1.1)
*Availability*: "CONFIG_VNC"
@@ -11924,7 +11924,7 @@ Command query-display-options (Since: 3.
Return information about display configuration
Return:
- "DisplayOptions" -- "DisplayOptions"
+ "DisplayOptions"
Clause 4. Else return goes right after the intro. Good.
Enum DisplayReloadType (Since: 6.0)
@@ -12363,7 +12363,7 @@ Command query-migrate (Since: 0.14)
status.
Return:
- "MigrationInfo" -- "MigrationInfo"
+ "MigrationInfo"
Clause 4. Else return goes right after the intro. Good.
Example: Before the first migration:
@@ -12590,7 +12590,7 @@ Command query-migrate-capabilities (Sinc
Return information about the current migration capabilities status
Return:
- "[""MigrationCapabilityStatus""]" -- "MigrationCapabilityStatus"
+ "[""MigrationCapabilityStatus""]"
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -13282,7 +13282,7 @@ Command query-migrate-parameters (Since:
Return information about the current migration parameters
Return:
- "MigrationParameters" -- "MigrationParameters"
+ "MigrationParameters"
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -13759,8 +13759,7 @@ Command query-xen-replication-status (Si
Query replication status while the vm is running.
Return:
- "ReplicationStatus" -- A "ReplicationStatus" object showing the - status. + "ReplicationStatus"
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -13801,7 +13800,7 @@ Command query-colo-status (Since: 3.1)
Query COLO status while the vm is running.
Return:
- "COLOStatus" -- A "COLOStatus" object showing the status.
+ "COLOStatus"
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -14094,13 +14093,13 @@ Command query-migrationthreads (Since: 7
Return information of migration threads
+ Return:
+ "[""MigrationThreadInfo""]"
+
Clause 3. Else if we have features, return goes right before them. The move is good.
Features:
* **deprecated** -- This command is deprecated with no replacement yet.
- Return:
- "[""MigrationThreadInfo""]" -- "MigrationThreadInfo"
-
Command snapshot-save (Since: 6.0)
Save a VM snapshot
@@ -16596,7 +16595,7 @@ Command query-cpus-fast (Since: 2.12)
Return information about all virtual CPUs.
Return:
- "[""CpuInfoFast""]" -- list of "CpuInfoFast"
+ "[""CpuInfoFast""]"
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -16694,12 +16693,12 @@ Command query-machines (Since: 1.2)
* **compat-props** ("boolean", *optional*) -- if true, also return compatibility properties. (default: false) (since 9.1)
+ Return:
+ "[""MachineInfo""]"
+
Clause 1. If we have arguments, return goes right after them. The move is good.
Features:
* **unstable** -- Argument "compat-props" is experimental.
- Return:
- "[""MachineInfo""]" -- a list of MachineInfo
-
Example::
-> { "execute": "query-machines", "arguments": { "compat-props": true } } @@ -16736,7 +16735,7 @@ Command query-current-machine (Since: 4.
Return information on the current virtual machine.
Return:
- "CurrentMachineParams" -- CurrentMachineParams
+ "CurrentMachineParams"
Clause 4. Else return goes right after the intro. Good.
Object QemuTargetInfo (Since: 1.2)
@@ -16750,7 +16749,7 @@ Command query-target (Since: 1.2)
Return information about the target for this QEMU
Return:
- "QemuTargetInfo" -- QemuTargetInfo
+ "QemuTargetInfo"
Clause 4. Else return goes right after the intro. Good.
Object UuidInfo (Since: 0.14)
@@ -16769,7 +16768,7 @@ Command query-uuid (Since: 0.14)
Query the guest UUID information.
Return:
- "UuidInfo" -- The "UuidInfo" for the guest
+ "UuidInfo"
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -16893,7 +16892,7 @@ Command query-kvm (Since: 0.14)
Return information about KVM acceleration
Return:
- "KvmInfo" -- "KvmInfo"
+ "KvmInfo"
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -17267,7 +17266,7 @@ Command query-memdev (Since: 2.1)
Return information for all memory backends.
Return:
- "[""Memdev""]" -- a list of "Memdev".
+ "[""Memdev""]"
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -17359,7 +17358,7 @@ Object HotpluggableCPU (Since: 2.7)
Command query-hotpluggable-cpus (Since: 2.7)
Return:
- "[""HotpluggableCPU""]" -- a list of HotpluggableCPU objects.
+ "[""HotpluggableCPU""]"
Clause 4. Else return goes right after the intro. Good.
Example:: For pseries machine type started with "-smp 2,cores=2,maxcpus=4 -cpu POWER8":
@@ -17457,7 +17456,7 @@ Command query-balloon (Since: 0.14)
Return information about the balloon device.
Return:
- "BalloonInfo" -- "BalloonInfo"
+ "BalloonInfo"
Clause 2. Else if we have errors, return goes right before them. Good.
Errors:
* If the balloon driver is enabled but not functional because
@@ -17511,7 +17510,7 @@ Command query-hv-balloon-status-report (
"STATUS" message from the guest.
Return:
- "HvBalloonInfo" -- "HvBalloonInfo"
+ "HvBalloonInfo"
Clause 2. Else if we have errors, return goes right before them. Good.
Errors:
* If no hv-balloon device is present, guest memory status
@@ -18595,7 +18594,7 @@ Command query-yank (Since: 6.0)
Query yank instances. See "YankInstance" for more information.
Return:
- "[""YankInstance""]" -- list of "YankInstance"
+ "[""YankInstance""]"
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -18649,7 +18648,7 @@ Command query-name (Since: 0.14)
Return the name information of a guest.
Return:
- "NameInfo" -- "NameInfo" of the guest
+ "NameInfo"
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -18885,7 +18884,7 @@ Command add-fd (Since: 1.2)
can be used to describe the fd.
Return:
- "AddfdInfo" -- "AddfdInfo"
+ "AddfdInfo"
Clause 1. If we have arguments, return goes right after them. Good.
Errors:
* If file descriptor was not received, GenericError
@@ -18958,7 +18957,7 @@ Command query-fdsets (Since: 1.2)
Return information describing all fd sets.
Return:
- "[""FdsetInfo""]" -- A list of "FdsetInfo"
+ "[""FdsetInfo""]"
Clause 4. Else return goes right after the intro. Good.
Note:
@@ -19247,7 +19246,7 @@ Command query-sev (Since: 2.12)
is unspecified.
Return:
- "SevInfo" -- "SevInfo"
+ "SevInfo"
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -19312,7 +19311,7 @@ Command query-sev-capabilities (Since: 2
This is only supported on AMD X86 platforms with KVM enabled.
Return:
- "SevCapability" -- SevCapability objects.
+ "SevCapability"
Clause 2. Else if we have errors, return goes right before them. Good.
Errors:
* If SEV is not available on the platform, GenericError
@@ -19370,7 +19369,7 @@ Command query-sev-attestation-report (Si
base64 (it will be included in report)
Return:
- "SevAttestationReport" -- SevAttestationReport objects.
+ "SevAttestationReport"
Clause 1. If we have arguments, return goes right after them. Good.
Errors:
* This will return an error if the attestation report is
@@ -19414,7 +19413,7 @@ Command query-sgx (Since: 6.2)
Return information about configured SGX capabilities of guest
Return:
- "SgxInfo" -- "SgxInfo"
+ "SgxInfo"
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -19429,7 +19428,7 @@ Command query-sgx-capabilities (Since: 6
Return information about SGX capabilities of host
Return:
- "SgxInfo" -- "SgxInfo"
+ "SgxInfo"
Clause 4. Else return goes right after the intro. Good.
Example::
@@ -19946,7 +19945,7 @@ Command query-audiodevs (Since: 8.0)
Return information about audiodev configuration
Return:
- "[""Audiodev""]" -- array of "Audiodev"
+ "[""Audiodev""]"
Clause 4. Else return goes right after the intro. Good.
ACPI
@@ -21238,12 +21237,12 @@ Command x-query-virtio-queue-element (Si
* **index** ("int", *optional*) -- Index of the element in the queue (default: head of the queue)
+ Return:
+ "VirtioQueueElement"
+
Clause 1. If we have arguments, return goes right after them. The move is good.
Features:
* **unstable** -- This command is meant for debugging.
- Return:
- "VirtioQueueElement" -- VirtioQueueElement information
-
Example: Introspect on virtio-net's VirtQueue 0 at index 5:
-> { "execute": "x-query-virtio-queue-element",
@@ -21494,7 +21493,7 @@ Command query-cryptodev (Since: 8.0)
Return information about current crypto devices.
Return:
- "[""QCryptodevInfo""]" -- a list of "QCryptodevInfo"
+ "[""QCryptodevInfo""]"
Clause 4. Else return goes right after the intro. Good.
CXL devices
Placement is all good.
Two more Returns: sections this patch should remove:
# @query-cpu-definitions:
#
# Return a list of supported virtual CPU definitions
#
# Returns: a list of CpuDefinitionInfo
#
# Since: 1.2
##
{ 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'] }and
##
# @query-gic-capabilities:
#
# It will return a list of `GICCapability` objects that describe its
# capability bits.
#
# 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::
#
# -> { "execute": "query-gic-capabilities" }
# <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
# { "version": 3, "emulated": false, "kernel": true } ] }
##
{ 'command': 'query-gic-capabilities', 'returns': ['GICCapability'] }Tracked down with
$ git-grep '# Returns:.*`'
with your "[PATCH v2 00/18] QAPI: add cross-references to qapi docs" applied. Shows lines containing QAPI names, which your series helpfully puts into backquotes for easy grepping.
With these two removed, and the commit message amended to note the moves:
Re: [PATCH v6 4/4] qapi: rephrase return docs to avoid type name
In reply to John SnowQuoted 1 line · John Snow
Well, I tried. Maybe not very hard. Sorry!
Recommend to explain *why* we want to avoid the 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.
Quoted 26 lines
Signed-off-by John Snow <[email protected]>--- 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/misc-i386.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 +++--- 17 files changed, 28 insertions(+), 34 deletions(-)qapi/block-core.json +0
-0
qapi/block-core.json line 764
Quoted 2 lines
qapi/block-core.json +0
-0@@ -763,7 +763,7 @@ # # Get a list of BlockInfo for all virtual block devices.
Mentioning the type in the intro is commonly just as redundant as in Returns:.
qapi/block-core.json line 766
Quoted 3 lines
qapi/block-core.json +1
-1# -# Returns: a list of @BlockInfo describing each virtual block device. +# Returns: a list describing each virtual block device.
"A list" is arguably just as redundant as the list's element type.
The entire line is pretty redundant with the intro.
qapi/block-core.json
Quoted 4 lines
qapi/block-core.json +0
-0# 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)
qapi/block-core.json line 1171
Quoted 3 lines
qapi/block-core.json +1
-1# -# Returns: A list of @BlockStats for each virtual block devices. +# Returns: A list of statistics for each virtual block device.
Again, the entire line is pretty redundant with the intro.
qapi/block-core.json line 1443
Quoted 9 lines
qapi/block-core.json +1
-1# # 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
Best not to abbreviate "information" to "info".
qapi/block-core.json line 1446
Quoted 3 lines
qapi/block-core.json +0
-0# # Since: 1.1 ##
I need to stop here to take care of another series. Gut feeling so far:
right direction, doesn't go far enough.
Choices:
* Go far enough. Too close to the freeze for that, I'm afraid.
* Merge it basically as is, come back later to finish the job.
* Drop it for now, adjust your "QAPI: add cross-references to qapi docs" to enclose the type names not removed in backquotes.
Thoughts?
[...]
Re: [PATCH v6 1/4] docs/qapi-domain: add return-nodesc
In reply to John SnowQuoted 24 lines · John Snow
This form is used to annotate a return type without an accompanying description, for when there is no "Returns:" information in the source doc, but we have a return type we want to generate a cross-reference to.
The syntax is:
:return-nodesc: TypeName
It's primarily necessary because Sphinx always expects both a type and a description for the prior form and will format it accordingly. To have a reasonable rendering when the body is missing, we need to use a different info field list entirely.
Signed-off-by John Snow <[email protected]>--- docs/devel/qapi-domain.rst | 30 ++++++++++++++++++++++++++++++ docs/sphinx/qapi_domain.py | 8 ++++++++ 2 files changed, 38 insertions(+)docs/devel/qapi-domain.rst +0
-0
docs/devel/qapi-domain.rst Example:: · line 248
Quoted 7 lines
docs/devel/qapi-domain.rst +4
-0@@ -242,6 +242,36 @@ Example:: } +``:return-nodesc:`` +------------------- + +Document the return type of a QAPI command, without an accompanying description.
Recommend to break the long line.
Quoted 16 lines
docs/devel/qapi-domain.rst +16
-0+ +:availability: This field list is only available in the body of the + Command directive. +:syntax: ``:return-nodesc: type`` +:type: `sphinx.util.docfields.Field + <https://pydoc.dev/sphinx/latest/sphinx.util.docfields.Field.html?private=1>`_ + + +Example:: + + .. qapi:command:: query-replay + :since: 5.2 + + Retrieve the record/replay information. It includes current + instruction count which may be used for ``replay-break`` and + ``replay-seek`` commands.
docs/devel/qapi-domain.rst Example:: · line 274
Quoted 10 lines
docs/devel/qapi-domain.rst +10
-0+ + :return-nodesc: ReplayInfo + + .. qmp-example:: + + -> { "execute": "query-replay" } + <- { "return": { + "mode": "play", "filename": "log.rr", "icount": 220414 } + } +
Same example as in :return:, except for the :return-nodesc: line. Fine with me.
Quoted 11 lines
docs/devel/qapi-domain.rst +0
-0``:value:`` -----------docs/sphinx/qapi_domain.py +0
-0@@ -532,6 +532,14 @@ class QAPICommand(QAPIObject): names=("return",), can_collapse=True, ),
docs/sphinx/qapi_domain.py class QAPICommand(QAPIObject): · line 544
Quoted 10 lines
docs/sphinx/qapi_domain.py +8
-0+ # :return-nodesc: TypeName + CompatField( + "returnvalue", + label=_("Return"), + names=("return-nodesc",), + bodyrolename="type", + has_arg=False, + ), ] )
Markus Armbruster
Acked-byRe: [PATCH v6 4/4] qapi: rephrase return docs to avoid type name
In reply to Markus ArmbrusterQuoted 11 lines · Markus Armbruster
Quoted 1 line · John Snow
Well, I tried. Maybe not very hard. Sorry!
Recommend to explain *why* we want to avoid the 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.
Quoted 1 line
Signed-off-by John Snow <[email protected]>
[...]
Quoted 8 lines
I need to stop here to take care of another series. Gut feeling so far:
right direction, doesn't go far enough.Choices:
* Go far enough. Too close to the freeze for that, I'm afraid.
* Merge it basically as is, come back later to finish the job.
Let's pick this one, then try to improve on top.
Quoted 6 lines
* Drop it for now, adjust your "QAPI: add cross-references to qapi docs" to enclose the type names not removed in
backquotes.Thoughts?
[...]
Markus Armbruster
AppliedQueued for 10.1. Thanks!