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(-)
--
2.50.0
