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.
For non-QAPI maintainers: You're likely being CC'd because of patches 3
& 4, which touches nearly every subsystem's QAPI documentation. Let me
know if you see any obvious issues. Don't worry about patches 1 & 2
unless you're particularly bored.
v4: rebased on origin/master (2025-06-12)
Review comments:
Markus: From what I recall, you had questions concerning the
insertion position of the "Returns:" stub in patch 2. I picked
something somewhat arbitrarily, and you were uneasy with the
laissez-faire approach. I'm more than happy to change it, but
request that you decide on the order/algorithm for insertion.
From memory, I chose an insertion position that favors putting
"Returns:" as the last info field; i.e. if any other info fields are
present, we put ours immediately after the last one. If there are
none at all, we just put it last. This may or may not cause ordering
issues depending on your taste.
(I am also content to change *where* the insertion occurs, but I
think inserting it in the parser makes enough sense to leave it
alone, unless you have concerns.)
Patch 3 should be fine, though possibly incomplete depending on taste.
Patch 4 is the likeliest to be subject to copyediting nits, and on
this patch I heavily encourage you to write your own fixup patch
which I will *happily and with glee* merge into this patch. Whatever
phrasing you prefer here I am more than happy to take. You did in
fact have a number of nits in response to v1/v2, but I admit I did
not apply them - in favor of nudging you to do the copy-editing
you'd like to see directly instead. (Sorry!)
This patch is also possibly incomplete depending on taste.
v3: rebased on top of python-qapi-linting (v4) pull request;
removed commits that are no longer needed.
Markus: I forget where we left off... shall we refresh?
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 | 22 ----------------------
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 | 1 -
scripts/qapi/parser.py | 15 +++++++++++++++
scripts/qapi/schema.py | 3 +++
31 files changed, 92 insertions(+), 132 deletions(-)
--
2.48.1
