qapi: add auto-generated return docs
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
- v6 Latest4 patches 6 repliesApplied
- v54 patches 1 replySuperseded
- v44 patches 0 repliesSuperseded
Earlier versions · 3
| Version | Posted | Patches | Replies | Status |
|---|---|---|---|---|
| v3 | 4 patches | 3 replies | Applied | |
| v2 | 4 patches | 7 replies | Superseded | |
| v1 | 4 patches | 9 replies | Superseded |
Patches in v6 Applied
| # | Subject and files | Size | Replies | Applied |
|---|---|---|---|---|
| 1/4 | docs/qapi-domain: add return-nodescdocs/ docs/ | +38 | 1 reply | |
| 2/4 | docs, qapi: generate undocumented return sectionsdocs/ qapi/ scripts/ +1 more | +48 | 1 reply | |
| 3/4 | qapi: remove trivial "Returns:" sectionsqapi/ qapi/ qapi/ +11 more | +3 | 1 reply | |
| 4/4 | qapi: rephrase return docs to avoid type nameqapi/ qapi/ qapi/ +14 more | +28 | 2 replies |
Reviews trailers per patch
All 4 patches have a Reviewed-by or Acked-by.
| Patch | Markus Armbruster |
|---|---|
| 1/4 | A-b |
| 2/4 | R-b |
| 3/4 | R-b |
| 4/4 | A-b |
Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes.
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