[v5] qapi: add auto-generated return docs

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

John Snow posted 4 patches 4 months, 3 weeks ago

Diff against v1 v2 v3 v4 v6
Download series mbox

Patches applied successfully (tree, apply log)
git fetch https://github.com/patchew-project/qemu tags/patchew/20250626195337.2158250-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>

There is a newer version of this series

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     | 34 ++++++++++++++++++++++++++++++++++
scripts/qapi/schema.py     |  3 +++
31 files changed, 111 insertions(+), 132 deletions(-)

Expand all Fold all

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

Posted by John Snow 4 months, 3 weeks 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.

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          | 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     | 34 ++++++++++++++++++++++++++++++++++
 scripts/qapi/schema.py     |  3 +++
 31 files changed, 111 insertions(+), 132 deletions(-)

-- 
2.48.1