[PATCH v4 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.

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