[PATCH v6 0/4] qapi: add auto-generated return docs

[John Snow <jsnow@redhat.com>]

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