Skip to content

qapi: add auto-generated return docs

John Snow qemu-devel qemu-trivial 6 versions – Applied

Status from this message: Queued for 10.1. Thanks!

Get series with b4
b4 am [email protected]

Versions newest first · linked by author and title

  1. v6 Latest4 patches 6 repliesApplied
  2. v54 patches 1 replySuperseded
  3. v44 patches 0 repliesSuperseded
Earlier versions · 3
VersionPostedPatchesRepliesStatus
v34 patches3 repliesApplied
v24 patches7 repliesSuperseded
v14 patches9 repliesSuperseded

Patches in v6 Applied

#Subject and filesSizeRepliesApplied
1/4docs/qapi-domain: add return-nodescdocs/devel/qapi-domain.rst docs/sphinx/qapi_domain.py+38 -01 reply
2/4docs, qapi: generate undocumented return sectionsdocs/sphinx/qapidoc.py qapi/machine.json scripts/qapi/parser.py +1 more+48 -61 reply
3/4qapi: remove trivial "Returns:" sectionsqapi/audio.json qapi/block-core.json qapi/char.json +11 more+3 -901 reply
4/4qapi: rephrase return docs to avoid type nameqapi/block-core.json qapi/block-export.json qapi/block.json +14 more+28 -342 replies

Reviews trailers per patch

All 4 patches have a Reviewed-by or Acked-by.

PatchMarkus Armbruster
1/4A-b
2/4R-b
3/4R-b
4/4A-b

Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes.

Read the v6 thread

Cover letter [PATCH v6 0/4] 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