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-target.json   |  9 +++------
 qapi/machine.json          | 22 ----------------------
 qapi/migration.json        | 12 ------------
 qapi/misc-target.json      | 14 +-------------
 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 +++
 32 files changed, 95 insertions(+), 140 deletions(-)

-- 
2.48.1

On 23.05.2025 21:24, John Snow wrote:
> 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

I've applied the first 2 patches to the trivial-patches tree.

But the remaining 2 does not apply anymore due to reorg of
the json files for single-binary.

I tried to fiddle with the patches a bit, but it looks like
it'd be better if the original author will do that, to avoid
my mistakes :)

Thanks,

/mjt

Michael Tokarev <mjt@tls.msk.ru> writes:

> On 23.05.2025 21:24, John Snow wrote:
>> 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
>
> I've applied the first 2 patches to the trivial-patches tree.
>
> But the remaining 2 does not apply anymore due to reorg of
> the json files for single-binary.
>
> I tried to fiddle with the patches a bit, but it looks like
> it'd be better if the original author will do that, to avoid
> my mistakes :)

I'd like to take all four through my tree after I reviewed them.

Sorry for the delay!

On Fri, May 23, 2025 at 02:24:38PM -0400, John Snow wrote:
> 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 :(


LGTM
My bits:

Acked-by: Michael S. Tsirkin <mst@redhat.com>

feel free to merge


> 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-target.json   |  9 +++------
>  qapi/machine.json          | 22 ----------------------
>  qapi/migration.json        | 12 ------------
>  qapi/misc-target.json      | 14 +-------------
>  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 +++
>  32 files changed, 95 insertions(+), 140 deletions(-)
> 
> -- 
> 2.48.1
>