qapi: add auto-generated return docs
cover qapi: add auto-generated return docs
Basically RFC quality, I'm sure there's going to be a ton of back and forth on the doc phrasing changes. Ah well.
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-target.json | 9 +++------ qapi/machine.json | 22 ---------------------- qapi/migration.json | 12 ------------ qapi/misc-target.json | 14 +------------- 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 | 1 - scripts/qapi/parser.py | 11 +++++++++++ scripts/qapi/schema.py | 3 +++ 32 files changed, 91 insertions(+), 140 deletions(-)
Signature · 1 line
2.48.1
PATCH 1/4 docs/qapi-domain: add return-nodesc
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.
--- 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
@@ -529,6 +529,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.48.1
PATCH 2/4 docs, qapi: generate undocumented return sections
In reply to John SnowThis patch changes the qapidoc transmogrifier to generate Return value documentation for any command that has a return value but hasn't explicitly documented that return value.
--- docs/sphinx/qapidoc.py | 14 ++++++++------ scripts/qapi/parser.py | 11 +++++++++++ scripts/qapi/schema.py | 3 +++ 3 files changed, 22 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 ret_type 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
scripts/qapi/parser.py +11 -0
@@ -815,6 +815,17 @@ def connect_feature(self, feature: 'QAPISchemaFeature') -> None: % feature.name) self.features[feature.name].connect(feature) + def ensure_returns(self, info: QAPISourceInfo) -> None: + if not any(s.kind == QAPIDoc.Kind.RETURNS for s in self.all_sections): + + # Stub "Returns" section for undocumented returns value. + # Insert stub after the last non-PLAIN section. + for sect in reversed(self.all_sections): + if sect.kind != QAPIDoc.Kind.PLAIN: + stub = QAPIDoc.Section(info, QAPIDoc.Kind.RETURNS) + idx = self.all_sections.index(sect) + 1 + self.all_sections.insert(idx, 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.48.1
Re: [PATCH 2/4] docs, qapi: generate undocumented return sections
Quoted 5 lines · John Snow
This patch changes the qapidoc transmogrifier to generate Return value documentation for any command that has a return value but hasn't explicitly documented that return value.
Signed-off-by John Snow <[email protected]>
A number of commands lack return value documentation before the patch. These are:
QGA: guest-network-get-route
QMP: x-debug-query-block-graph, query-tpm, query-dirty-rate,
query-vcpu-dirty-limit, query-vm-generation-id, query-memory-size-summary, query-memory-devices, query-acpi-ospm-status, query-stats-schemas, query-stats-schemas
This patch fixes that. However, in my testing, it adds the missing "Return:" doc *twice* for x-debug-query-block-graph and query-dirty-rate.
Re: [PATCH 2/4] docs, qapi: generate undocumented return sections
Quoted 13 lines · Markus Armbruster
Quoted 5 lines · John Snow
This patch changes the qapidoc transmogrifier to generate Return value documentation for any command that has a return value but hasn't explicitly documented that return value.
Signed-off-by John Snow <[email protected]>A number of commands lack return value documentation before the patch. These are:
QGA: guest-network-get-route
Quoted 8 lines
QMP: x-debug-query-block-graph, query-tpm, query-dirty-rate,
query-vcpu-dirty-limit, query-vm-generation-id, query-memory-size-summary, query-memory-devices, query-acpi-ospm-status, query-stats-schemas, query-stats-schemasThis patch fixes that. However, in my testing, it adds the missing "Return:" doc *twice* for x-debug-query-block-graph and query-dirty-rate.
Guess who forgot a "break" statement?
--js
Re: [PATCH 2/4] docs, qapi: generate undocumented return sections
In reply to John SnowQuoted 5 lines · John Snow
This patch changes the qapidoc transmogrifier to generate Return value documentation for any command that has a return value but hasn't explicitly documented that return value.
Signed-off-by John Snow <[email protected]>
[...]
scripts/qapi/parser.py def connect_feature(self, feature: 'QAPISchemaFeature') -> None: · line 822
Quoted 13 lines
scripts/qapi/parser.py +5
-0@@ -815,6 +815,17 @@ def connect_feature(self, feature: 'QAPISchemaFeature') -> None: % feature.name) self.features[feature.name].connect(feature) + def ensure_returns(self, info: QAPISourceInfo) -> None: + if not any(s.kind == QAPIDoc.Kind.RETURNS for s in self.all_sections): + + # Stub "Returns" section for undocumented returns value. + # Insert stub after the last non-PLAIN section.
Can you explain why that's where it should go?
Should we tighten section order some more?
Quoted 23 lines
scripts/qapi/parser.py +6
-0+ for sect in reversed(self.all_sections): + if sect.kind != QAPIDoc.Kind.PLAIN: + stub = QAPIDoc.Section(info, QAPIDoc.Kind.RETURNS) + idx = self.all_sections.index(sect) + 1 + self.all_sections.insert(idx, 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(
Re: [PATCH 2/4] docs, qapi: generate undocumented return sections
Quoted 19 lines · Markus Armbruster
Quoted 5 lines · John Snow
This patch changes the qapidoc transmogrifier to generate Return value documentation for any command that has a return value but hasn't explicitly documented that return value.
Signed-off-by John Snow <[email protected]>[...]
scripts/qapi/parser.py def connect_feature(self, feature:
Quoted 5 lines
scripts/qapi/parser.py +0
-0@@ -815,6 +815,17 @@ def connect_feature(self, feature:'QAPISchemaFeature') -> None:
Quoted 3 lines
scripts/qapi/parser.py +0
-0% feature.name) self.features[feature.name].connect(feature)
Quoted 9 lines
scripts/qapi/parser.py def connect_feature(self, feature: · line 819
Quoted 2 lines
scripts/qapi/parser.py +2
-0+ def ensure_returns(self, info: QAPISourceInfo) -> None: + if not any(s.kind == QAPIDoc.Kind.RETURNS for s inself.all_sections):
scripts/qapi/parser.py def connect_feature(self, feature: 'QAPISchemaFeature') -> None: · line 822
Quoted 3 lines
scripts/qapi/parser.py +3
-0+ + # Stub "Returns" section for undocumented returns value. + # Insert stub after the last non-PLAIN section.Can you explain why that's where it should go?
... No.
(Joking...)
I'm open to better positions if you can define them, admittedly I just picked a place that's likely to be at the end of the info field list sections. (Reminder: "info field list" means the sections that are converted directly into the two-column layout section of the rendered docs.)
Quoted 3 lines
Should we tighten section order some more?
I wouldn't mind, but I believe this needs to be a change that you direct. From memory, I believe my preferred "enforced order" is something like this:
1. Intro paragraph(s)
2. Members
3. Features
4. Errors
5. Returns
6. Detail paragraph(s)
...Give or take some re-ordering between features/errors/returns as appropriate, I don't actually really care about the order there so much as I care about the fact that plain paragraphs do not appear between the members-features-errors-returns "region". The rest can be your preference.
(Since and TODO can go wherever, from the perspective of the transmogrifier, I do not care about them since I do not render them in the document flow.)
Quoted 27 lines
scripts/qapi/schema.py def connect_doc(self, doc: Optional[QAPIDoc] =
Quoted 15 lines
scripts/qapi/parser.py +6
-0+ for sect in reversed(self.all_sections): + if sect.kind != QAPIDoc.Kind.PLAIN: + stub = QAPIDoc.Section(info, QAPIDoc.Kind.RETURNS) + idx = self.all_sections.index(sect) + 1 + self.all_sections.insert(idx, 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@@ -1062,6 +1062,9 @@ def connect_doc(self, doc: Optional[QAPIDoc] =None) -> None:
Quoted 9 lines
scripts/qapi/schema.py +3
-0if 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(
Re: [PATCH 2/4] docs, qapi: generate undocumented return sections
Quoted 58 lines · John Snow
Quoted 19 lines · Markus Armbruster
Quoted 5 lines · John Snow
This patch changes the qapidoc transmogrifier to generate Return value documentation for any command that has a return value but hasn't explicitly documented that return value.
Signed-off-by John Snow <[email protected]>[...]
scripts/qapi/parser.py def connect_feature(self, feature:
Quoted 5 lines
scripts/qapi/parser.py +0
-0@@ -815,6 +815,17 @@ def connect_feature(self, feature:'QAPISchemaFeature') -> None:
Quoted 3 lines
scripts/qapi/parser.py +0
-0% feature.name) self.features[feature.name].connect(feature)Quoted 9 lines
scripts/qapi/parser.py def connect_feature(self, feature: · line 819
Quoted 2 lines
scripts/qapi/parser.py +2
-0+ def ensure_returns(self, info: QAPISourceInfo) -> None: + if not any(s.kind == QAPIDoc.Kind.RETURNS for s inself.all_sections):
scripts/qapi/parser.py def connect_feature(self, feature: 'QAPISchemaFeature') -> None: · line 822
Quoted 3 lines
scripts/qapi/parser.py +3
-0+ + # Stub "Returns" section for undocumented returns value. + # Insert stub after the last non-PLAIN section.Can you explain why that's where it should go?
... No.
(Joking...)
I'm open to better positions if you can define them, admittedly I just picked a place that's likely to be at the end of the info field list sections. (Reminder: "info field list" means the sections that are converted directly into the two-column layout section of the rendered docs.)
Quoted 3 lines
Should we tighten section order some more?
I wouldn't mind, but I believe this needs to be a change that you direct. From memory, I believe my preferred "enforced order" is something like this:
1. Intro paragraph(s)
2. Members
3. Features
4. Errors
5. Returns
6. Detail paragraph(s)
Quoted 9 lines
...Give or take some re-ordering between features/errors/returns as appropriate, I don't actually really care about the order there so much as I care about the fact that plain paragraphs do not appear between the members-features-errors-returns "region". The rest can be your preference.
(Since and TODO can go wherever, from the perspective of the transmogrifier, I do not care about them since I do not render them in the document flow.)
With the insertions fixed to not duplicate/triplicate things, I notice these (unintentional) changes:
- x-debug-block-dirty-bitmap-sha256 moves returns from above errors to below
- blockdev-snapshot-delete-internal-sync ditto
- query-xen-replication-status ditto
- query-colo-status ditto
- query-balloon ditto
- query-hv-balloon-status-report ditto
- query-yank -- this one actually moves it from above what would be details to below -- this creates a new ambiguous case as we discussed on call earlier today.
- add-fd goes from above errors to below errors again.
Quoted 29 lines
Quoted 29 lines
scripts/qapi/schema.py def connect_doc(self, doc: Optional[QAPIDoc] =
Quoted 17 lines
scripts/qapi/parser.py +6
-0+ for sect in reversed(self.all_sections): + if sect.kind != QAPIDoc.Kind.PLAIN: + stub = QAPIDoc.Section(info, QAPIDoc.Kind.RETURNS) + idx = self.all_sections.index(sect) + 1 + self.all_sections.insert(idx, 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@@ -1062,6 +1062,9 @@ def connect_doc(self, doc: Optional[QAPIDoc] =None) -> None:
Quoted 9 lines
scripts/qapi/schema.py +3
-0if 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(
Re: [PATCH 2/4] docs, qapi: generate undocumented return sections
Quoted 13 lines · John Snow
With the insertions fixed to not duplicate/triplicate things, I notice these (unintentional) changes:
- x-debug-block-dirty-bitmap-sha256 moves returns from above errors to below
- blockdev-snapshot-delete-internal-sync ditto
- query-xen-replication-status ditto
- query-colo-status ditto
- query-balloon ditto
- query-hv-balloon-status-report ditto
- query-yank -- this one actually moves it from above what would be details to below -- this creates a new ambiguous case as we discussed on call earlier today.
- add-fd goes from above errors to below errors again.
ACK. Let's discuss this in review of v2.
[...]
PATCH 3/4 qapi: remove trivial "Returns:" sections
In reply to John SnowThe new qapidoc transmogrifier 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 does not touch Returns: lines that add some information (potentially helpful, potentially not) but repeats the type information to remove that type.
--- qapi/audio.json | 2 -- qapi/block-core.json | 8 -------- qapi/char.json | 8 -------- qapi/cryptodev.json | 2 -- qapi/machine-target.json | 2 -- qapi/machine.json | 22 ---------------------- qapi/migration.json | 12 ------------ qapi/misc-target.json | 12 ------------ 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 | 1 - 15 files changed, 96 deletions(-)
qapi/audio.json +0 -2
@@ -535,8 +535,6 @@ # # Returns information about audiodev configuration # -# Returns: array of @Audiodev -# # Since: 8.0 ## { 'command': 'query-audiodevs',
qapi/block-core.json +0 -8
@@ -1949,8 +1949,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
@@ -6157,9 +6152,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 @@ # # Returns information about current character devices. # -# Returns: a list of @ChardevInfo -# # Since: 0.14 # # .. qmp-example::
@@ -82,8 +80,6 @@ # # Returns 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 @@ # # Returns information about current crypto devices. # -# Returns: a list of @QCryptodevInfo -# # Since: 8.0 ## { 'command': 'query-cryptodev', 'returns': ['QCryptodevInfo']}
qapi/machine-target.json +0 -2
@@ -391,8 +391,6 @@ # # Return a list of supported virtual CPU definitions # -# Returns: a list of CpuDefinitionInfo -# # Since: 1.2 ## { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'],
qapi/machine.json +0 -22
@@ -101,8 +101,6 @@ # # Returns 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: TargetInfo -# # Since: 1.2 ## { 'command': 'query-target', 'returns': 'TargetInfo' }
@@ -316,8 +308,6 @@ # # Query the guest UUID information. # -# Returns: The @UuidInfo for the guest -# # Since: 0.14 # # .. qmp-example::
@@ -469,8 +459,6 @@ # # Returns information about KVM acceleration # -# Returns: @KvmInfo -# # Since: 0.14 # # .. qmp-example::
@@ -932,8 +920,6 @@ # # Returns 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 @@ # Returns 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 +0 -12
@@ -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 @@ # # Returns information about the current migration capabilities status # -# Returns: @MigrationCapabilityStatus -# # Since: 1.2 # # .. qmp-example::
@@ -1322,8 +1318,6 @@ # # Returns information about the current migration parameters # -# Returns: @MigrationParameters -# # Since: 2.4 # # .. qmp-example::
@@ -1904,8 +1898,6 @@ # # Query replication status while the vm is running. # -# Returns: A @ReplicationStatus object showing the status. -# # .. qmp-example:: # # -> { "execute": "query-xen-replication-status" }
@@ -1958,8 +1950,6 @@ # # Query COLO status while the vm is running. # -# Returns: A @COLOStatus object showing the status. -# # .. qmp-example:: # # -> { "execute": "query-colo-status" }
@@ -2333,8 +2323,6 @@ # # @deprecated: This command is deprecated with no replacement yet. # -# Returns: @MigrationThreadInfo -# # Since: 7.2 ## { 'command': 'query-migrationthreads',
qapi/misc-target.json +0 -12
@@ -129,8 +129,6 @@ # # Returns information about SEV # -# Returns: @SevInfo -# # Since: 2.12 # # .. qmp-example::
@@ -205,8 +203,6 @@ # This command is used to get the SEV capabilities, and is supported # on AMD X86 platforms only. # -# Returns: SevCapability objects. -# # Since: 2.12 # # .. qmp-example::
@@ -259,8 +255,6 @@ # @mnonce: a random 16 bytes value encoded in base64 (it will be # included in report) # -# Returns: SevAttestationReport objects. -# # Since: 6.1 # # .. qmp-example::
@@ -324,8 +318,6 @@ # This command is ARM-only. It will return a list of GICCapability # objects that describe its capability bits. # -# Returns: a list of GICCapability objects. -# # Since: 2.6 # # .. qmp-example::
@@ -382,8 +374,6 @@ # # Returns information about SGX # -# Returns: @SGXInfo -# # Since: 6.2 # # .. qmp-example::
@@ -401,8 +391,6 @@ # # Returns information from host SGX capabilities # -# 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 @@ # # Returns information about the current SPICE server # -# Returns: @SpiceInfo -# # Since: 0.14 # # .. qmp-example::
@@ -656,8 +654,6 @@ # # Returns information about the current VNC server # -# Returns: @VncInfo -# # Since: 0.14 # # .. qmp-example::
@@ -687,8 +683,6 @@ # # Returns 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 @@ # # Returns 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 -1
@@ -102,7 +102,6 @@ # # Query yank instances. See @YankInstance for more information. # -# Returns: list of @YankInstance # # .. qmp-example:: #
Signature · 1 line
2.48.1
Re: [PATCH 3/4] qapi: remove trivial "Returns:" sections
Quoted 10 lines · John Snow
The new qapidoc transmogrifier 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 does not touch Returns: lines that add some information (potentially helpful, potentially not) but repeats the type information to remove that type.
Signed-off-by John Snow <[email protected]>
This is a clear improvement for the generated docs. For instance, blockdev-snapshot-delete-internal-sync goes from
Return:
"SnapshotInfo" -- SnapshotInfo
to
Return:
"SnapshotInfo"
However, I see that *triplicated* in my testing. I observed similar issues with the previous patch, so let's discuss that there and ignore it here.
The impact on schema file egonomics is less clear.
This patch removes a bunch of "Returns:" sections that make the generated docs look bad. How can we stop people from writing such sections?
Developers tend to refer to the schema file instead of the generated documentation. Information is spread across doc comment and schema code. Both describe the syntactic structure. Only the schema code has types, optional, and such. The doc comment describes semantics. In practice, skimming the doc comment is often enough.
Except for the return value. The doc comment's "Returns:" section is optional. When it's absent, the generated docs are bad (but this patch fixes that). Moreover, the doc comment doesn't fully describe the syntactic structure then. Unwary readers may not be aware of that trap, and miss the return value.
The inliner you posted before needs to know where the inlined stuff goes. Obvious when there are argument descriptions or a "Returns:". For the cases where we have nothing useful, you proposed an explicit marker "Details:" (how exactly it's spelled doesn't matter here, only that an explicit marker can be necessary). Could removing "Returns:" make the marker necessary more often? Can our tooling reliably detect the need for the marker?
Re: [PATCH 3/4] qapi: remove trivial "Returns:" sections
Quoted 46 lines · Markus Armbruster
Quoted 10 lines · John Snow
The new qapidoc transmogrifier 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 does not touch Returns: lines that add some information (potentially helpful, potentially not) but repeats the type information to remove that type.
Signed-off-by John Snow <[email protected]>This is a clear improvement for the generated docs. For instance, blockdev-snapshot-delete-internal-sync goes from
Return:
"SnapshotInfo" -- SnapshotInfoto
Return:
"SnapshotInfo"However, I see that *triplicated* in my testing. I observed similar issues with the previous patch, so let's discuss that there and ignore it here.
The impact on schema file egonomics is less clear.
This patch removes a bunch of "Returns:" sections that make the generated docs look bad. How can we stop people from writing such sections?
Developers tend to refer to the schema file instead of the generated documentation. Information is spread across doc comment and schema code. Both describe the syntactic structure. Only the schema code has types, optional, and such. The doc comment describes semantics. In practice, skimming the doc comment is often enough.
Except for the return value. The doc comment's "Returns:" section is optional. When it's absent, the generated docs are bad (but this patch fixes that). Moreover, the doc comment doesn't fully describe the syntactic structure then. Unwary readers may not be aware of that trap, and miss the return value.
Quoted 8 lines
The inliner you posted before needs to know where the inlined stuff goes. Obvious when there are argument descriptions or a "Returns:". For the cases where we have nothing useful, you proposed an explicit marker "Details:" (how exactly it's spelled doesn't matter here, only that an explicit marker can be necessary). Could removing "Returns:" make the marker necessary more often? Can our tooling reliably detect the need for the marker?
Well, tooling can at least be certain when it isn't certain.
The warning I have in my inliner branch-fork-whatever now basically just looks at the sections and if there's non-plaintext sections between the start and the ending, it treats the beginning as intro and the ending as details.
In the case there is *nothing else at all*, i.e. no returns, no arguments/members, no errors, no features - i.e. it's a single QAPIDoc Section - the inliner will count the *paragraphs*. If it's *one* paragraph, it deduces that it's an intro section and does not consider it ambiguous. If there are multiple paragraphs, however, that's when it emits a warning.
A computer is never going to be able to reliably determine *intent*, but syntactically I think that's a pretty narrow circumstance to yelp over:
"Documentation contains only a single plaintext section that consists of two or more paragraphs". In practice, that's a reasonably rare occurrence and is most likely to occur with query commands that take no arguments, have no features, and do not document return value semantics.
Re: [PATCH 3/4] qapi: remove trivial "Returns:" sections
Quoted 30 lines · John Snow
Quoted 28 lines · Markus Armbruster
Quoted 10 lines · John Snow
The new qapidoc transmogrifier 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 does not touch Returns: lines that add some information (potentially helpful, potentially not) but repeats the type information to remove that type.
Signed-off-by John Snow <[email protected]>This is a clear improvement for the generated docs. For instance, blockdev-snapshot-delete-internal-sync goes from
Return:
"SnapshotInfo" -- SnapshotInfoto
Return:
"SnapshotInfo"However, I see that *triplicated* in my testing. I observed similar issues with the previous patch, so let's discuss that there and ignore it here.
Quoted 5 lines
Quoted 5 lines
The impact on schema file egonomics is less clear.
This patch removes a bunch of "Returns:" sections that make the generated docs look bad. How can we stop people from writing such sections?
Plan A: catch it in review. If that turns out to be overly bothersome, we need to think about better tooling.
Quoted 11 lines
Quoted 11 lines
Developers tend to refer to the schema file instead of the generated documentation. Information is spread across doc comment and schema code. Both describe the syntactic structure. Only the schema code has types, optional, and such. The doc comment describes semantics. In practice, skimming the doc comment is often enough.
Except for the return value. The doc comment's "Returns:" section is optional. When it's absent, the generated docs are bad (but this patch fixes that). Moreover, the doc comment doesn't fully describe the syntactic structure then. Unwary readers may not be aware of that trap, and miss the return value.
I've since pondered this some more, and also talked with John.
When doc comments look like they provide a certain kind of information, but they are actually unrealiable, that's less than ideal for its readers.
This has always been the case for member / argument descriptions. We didn't require them initially, and when we started to, things had gotten so bad that I had to provide an escape hatch: pragma documentation-exceptions still lists 44 offenders in qapi/ and one in qga/.
Most of the offenders are doc bugs. But not all: documenting the members of QKeyCode one by one would be silly.
It has also always been the case for return value descriptions. We still don't require them. Your series uncovered ten in qapi/ and one in qga/. Your series adds 46 in qapi/. Possibly more after review of the last patch. Missing Returns goes from rare to common.
This does not create doc bugs. Generated documentation actually improves.
I figure developers just have to mind that the doc comment need not be complete.
Quoted 9 lines
Quoted 8 lines
The inliner you posted before needs to know where the inlined stuff goes. Obvious when there are argument descriptions or a "Returns:". For the cases where we have nothing useful, you proposed an explicit marker "Details:" (how exactly it's spelled doesn't matter here, only that an explicit marker can be necessary). Could removing "Returns:" make the marker necessary more often? Can our tooling reliably detect the need for the marker?
Quoted 6 lines
Well, tooling can at least be certain when it isn't certain.
The warning I have in my inliner branch-fork-whatever now basically just looks at the sections and if there's non-plaintext sections between the start and the ending, it treats the beginning as intro and the ending as details.
The non-plaintext sections are: Returns, Errors, Since, TODO.
Returns and Errors are reliable anchors for the inliner. The inliner inlines argument sections. They need to go next to Returns / Errors sections, if any, because they get rendered together in as single two-column thing.
Since feels useless as an anchor. Does the inline ignore it? I don't remember. Every definition doc should have it, and we commonly put it at the very end (currently 776 out of 984 times). When we don't, it's usually followed by examples only, and occasionally by notes. Putting it always last would be better. If we manage to replace handwritten by computed since information, Since goes away.
TODO is the odd duck. It can go anywhere, which makes its use as anchor questionable. It's rare (I count 7 instances). One of them presses it into service to separate intro and example (commit 14b48aaab92). Your inliner series has a replacement for this hack; I believe the replacement can serve as a reliable anchor.
Quoted 5 lines
In the case there is *nothing else at all*, i.e. no returns, no arguments/members, no errors, no features - i.e. it's a single QAPIDoc Section - the inliner will count the *paragraphs*. If it's *one* paragraph, it deduces that it's an intro section and does not consider it ambiguous. If there are multiple paragraphs, however, that's when it emits a warning.
This is a heuristic. We'll discuss it in review of the inliner.
Quoted 5 lines
A computer is never going to be able to reliably determine *intent*, but syntactically I think that's a pretty narrow circumstance to yelp over:
"Documentation contains only a single plaintext section that consists of two or more paragraphs". In practice, that's a reasonably rare occurrence and is most likely to occur with query commands that take no arguments,
... or refer to a complex type for their arguments ...
Quoted 1 line
have no features, and do not document return value semantics.
... and do not document errors.
I'd be interested in the existing instances if you can track them down easily.
PATCH 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/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(-)
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 @@ # 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
qapi/control.json +2 -3
@@ -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 #
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 @@ # # 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 #
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
@@ -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 ##
qapi/machine-target.json +3 -4
@@ -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
qapi/misc-target.json +1 -1
@@ -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 #
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 @@ # # 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 #
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.48.1