[v6] qapi: add auto-generated return docs

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

John Snow posted 4 patches 5 months ago

Diff against v1 v2 v3 v4 v5
Download series mbox

Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/qemu tags/patchew/20250711051045.51110-1-jsnow@redhat.com

Maintainers: Markus Armbruster <armbru@redhat.com>, Michael Roth <michael.roth@amd.com>, John Snow <jsnow@redhat.com>, Peter Maydell <peter.maydell@linaro.org>, Eric Blake <eblake@redhat.com>, Gerd Hoffmann <kraxel@redhat.com>, "Marc-André Lureau" <marcandre.lureau@redhat.com>, Kevin Wolf <kwolf@redhat.com>, Hanna Reitz <hreitz@redhat.com>, Paolo Bonzini <pbonzini@redhat.com>, "Gonglei (Arei)" <arei.gonglei@huawei.com>, Zhenwei Pi <pizhenwei@bytedance.com>, Ani Sinha <anisinha@redhat.com>, Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>, Eduardo Habkost <eduardo@habkost.net>, Marcel Apfelbaum <marcel.apfelbaum@gmail.com>, "Philippe Mathieu-Daudé" <philmd@linaro.org>, Yanan Wang <wangyanan55@huawei.com>, Zhao Liu <zhao1.liu@intel.com>, Peter Xu <peterx@redhat.com>, Fabiano Rosas <farosas@suse.de>, Jason Wang <jasowang@redhat.com>, "Michael S. Tsirkin" <mst@redhat.com>, "Daniel P. Berrangé" <berrange@redhat.com>, Jiri Pirko <jiri@resnulli.us>, Stefan Berger <stefanb@linux.vnet.ibm.com>, Stefan Hajnoczi <stefanha@redhat.com>, Mads Ynddal <mads@ynddal.dk>, Lukas Straub <lukasstraub2@web.de>

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

Expand all Fold all

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

Posted by John Snow 5 months ago

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

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

Posted by Markus Armbruster 5 months ago

Queued for 10.1.  Thanks!