Subject: [PATCH 00/15] qapi: Improve command response documentation

[PATCH 00/13] Subject: [PATCH 00/15] qapi: Improve command response documentation

Markus Armbruster posted 13 patches 9 months ago

Download series mbox

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

Maintainers: Markus Armbruster <armbru@redhat.com>, Michael Roth <michael.roth@amd.com>, Kevin Wolf <kwolf@redhat.com>, Hanna Reitz <hreitz@redhat.com>, Eric Blake <eblake@redhat.com>, "Marc-André Lureau" <marcandre.lureau@redhat.com>, Paolo Bonzini <pbonzini@redhat.com>, Eduardo Habkost <eduardo@habkost.net>, Marcel Apfelbaum <marcel.apfelbaum@gmail.com>, "Philippe Mathieu-Daudé" <philmd@linaro.org>, Yanan Wang <wangyanan55@huawei.com>, Peter Xu <peterx@redhat.com>, Fabiano Rosas <farosas@suse.de>, Jason Wang <jasowang@redhat.com>, "Daniel P. Berrangé" <berrange@redhat.com>, Stefan Berger <stefanb@linux.vnet.ibm.com>, Gerd Hoffmann <kraxel@redhat.com>, Lukas Straub <lukasstraub2@web.de>, Konstantin Kostiuk <kkostiuk@redhat.com>

docs/devel/qapi-code-gen.rst               |  6 +-
qapi/block-core.json                       | 74 ++++++++--------------
qapi/block-export.json                     | 23 ++++---
qapi/block.json                            | 10 ++-
qapi/char.json                             |  6 --
qapi/dump.json                             |  2 -
qapi/machine-target.json                   | 37 ++++++-----
qapi/machine.json                          | 19 ++----
qapi/migration.json                        | 26 --------
qapi/misc-target.json                      |  3 -
qapi/misc.json                             | 25 +++-----
qapi/net.json                              | 17 +++--
qapi/qdev.json                             |  3 +-
qapi/qom.json                              |  6 +-
qapi/run-state.json                        |  5 +-
qapi/tpm.json                              |  2 -
qapi/transaction.json                      |  5 +-
qapi/ui.json                               | 17 +----
qapi/yank.json                             |  5 +-
qga/qapi-schema.json                       | 72 +++++++++------------
scripts/qapi/parser.py                     | 50 ++++++++++-----
tests/qapi-schema/doc-good.json            |  2 +
tests/qapi-schema/doc-good.out             |  2 +
tests/qapi-schema/doc-good.txt             |  6 ++
tests/qapi-schema/doc-invalid-return.err   |  2 +-
tests/qapi-schema/doc-invalid-return2.err  |  1 +
tests/qapi-schema/doc-invalid-return2.json |  7 ++
tests/qapi-schema/doc-invalid-return2.out  |  0
tests/qapi-schema/meson.build              |  1 +
29 files changed, 189 insertions(+), 245 deletions(-)
create mode 100644 tests/qapi-schema/doc-invalid-return2.err
create mode 100644 tests/qapi-schema/doc-invalid-return2.json
create mode 100644 tests/qapi-schema/doc-invalid-return2.out

Expand all Fold all

[PATCH 00/13] Subject: [PATCH 00/15] qapi: Improve command response documentation

Posted by Markus Armbruster 9 months ago

We use doc comment "Returns" sections both for success and error
response.  This series moves the latter to new "Errors" sections.
Enables some cleanup, visible in the diffstat.q

Markus Armbruster (13):
  qapi: Memorize since & returns sections
  qapi: Slightly clearer error message for invalid "Returns" section
  qapi: New documentation section tag "Errors"
  qapi: Move error documentation to new "Errors" sections
  qapi: Delete useless "Returns" sections
  qapi: Clean up "Returns" sections
  qapi/yank: Tweak @yank's error description for consistency
  qga/qapi-schema: Move error documentation to new "Errors" sections
  qga/qapi-schema: Delete useless "Returns" sections
  qga/qapi-schema: Clean up "Returns" sections
  qga/qapi-schema: Tweak documentation of fsfreeze commands
  qga/qapi-schema: Fix guest-set-memory-blocks documentation
  qapi: Reject "Returns" section when command doesn't return anything

 docs/devel/qapi-code-gen.rst               |  6 +-
 qapi/block-core.json                       | 74 ++++++++--------------
 qapi/block-export.json                     | 23 ++++---
 qapi/block.json                            | 10 ++-
 qapi/char.json                             |  6 --
 qapi/dump.json                             |  2 -
 qapi/machine-target.json                   | 37 ++++++-----
 qapi/machine.json                          | 19 ++----
 qapi/migration.json                        | 26 --------
 qapi/misc-target.json                      |  3 -
 qapi/misc.json                             | 25 +++-----
 qapi/net.json                              | 17 +++--
 qapi/qdev.json                             |  3 +-
 qapi/qom.json                              |  6 +-
 qapi/run-state.json                        |  5 +-
 qapi/tpm.json                              |  2 -
 qapi/transaction.json                      |  5 +-
 qapi/ui.json                               | 17 +----
 qapi/yank.json                             |  5 +-
 qga/qapi-schema.json                       | 72 +++++++++------------
 scripts/qapi/parser.py                     | 50 ++++++++++-----
 tests/qapi-schema/doc-good.json            |  2 +
 tests/qapi-schema/doc-good.out             |  2 +
 tests/qapi-schema/doc-good.txt             |  6 ++
 tests/qapi-schema/doc-invalid-return.err   |  2 +-
 tests/qapi-schema/doc-invalid-return2.err  |  1 +
 tests/qapi-schema/doc-invalid-return2.json |  7 ++
 tests/qapi-schema/doc-invalid-return2.out  |  0
 tests/qapi-schema/meson.build              |  1 +
 29 files changed, 189 insertions(+), 245 deletions(-)
 create mode 100644 tests/qapi-schema/doc-invalid-return2.err
 create mode 100644 tests/qapi-schema/doc-invalid-return2.json
 create mode 100644 tests/qapi-schema/doc-invalid-return2.out

-- 
2.43.0

Re: [PATCH 00/13] Subject: [PATCH 00/15] qapi: Improve command response documentation

Posted by Konstantin Kostiuk 8 months, 2 weeks ago

Hi Markus,

I will merge qga-related patches in my PULL.

Best Regards,
Konstantin Kostiuk.


On Tue, Feb 27, 2024 at 1:39 PM Markus Armbruster <armbru@redhat.com> wrote:

> We use doc comment "Returns" sections both for success and error
> response.  This series moves the latter to new "Errors" sections.
> Enables some cleanup, visible in the diffstat.q
>
> Markus Armbruster (13):
>   qapi: Memorize since & returns sections
>   qapi: Slightly clearer error message for invalid "Returns" section
>   qapi: New documentation section tag "Errors"
>   qapi: Move error documentation to new "Errors" sections
>   qapi: Delete useless "Returns" sections
>   qapi: Clean up "Returns" sections
>   qapi/yank: Tweak @yank's error description for consistency
>   qga/qapi-schema: Move error documentation to new "Errors" sections
>   qga/qapi-schema: Delete useless "Returns" sections
>   qga/qapi-schema: Clean up "Returns" sections
>   qga/qapi-schema: Tweak documentation of fsfreeze commands
>   qga/qapi-schema: Fix guest-set-memory-blocks documentation
>   qapi: Reject "Returns" section when command doesn't return anything
>
>  docs/devel/qapi-code-gen.rst               |  6 +-
>  qapi/block-core.json                       | 74 ++++++++--------------
>  qapi/block-export.json                     | 23 ++++---
>  qapi/block.json                            | 10 ++-
>  qapi/char.json                             |  6 --
>  qapi/dump.json                             |  2 -
>  qapi/machine-target.json                   | 37 ++++++-----
>  qapi/machine.json                          | 19 ++----
>  qapi/migration.json                        | 26 --------
>  qapi/misc-target.json                      |  3 -
>  qapi/misc.json                             | 25 +++-----
>  qapi/net.json                              | 17 +++--
>  qapi/qdev.json                             |  3 +-
>  qapi/qom.json                              |  6 +-
>  qapi/run-state.json                        |  5 +-
>  qapi/tpm.json                              |  2 -
>  qapi/transaction.json                      |  5 +-
>  qapi/ui.json                               | 17 +----
>  qapi/yank.json                             |  5 +-
>  qga/qapi-schema.json                       | 72 +++++++++------------
>  scripts/qapi/parser.py                     | 50 ++++++++++-----
>  tests/qapi-schema/doc-good.json            |  2 +
>  tests/qapi-schema/doc-good.out             |  2 +
>  tests/qapi-schema/doc-good.txt             |  6 ++
>  tests/qapi-schema/doc-invalid-return.err   |  2 +-
>  tests/qapi-schema/doc-invalid-return2.err  |  1 +
>  tests/qapi-schema/doc-invalid-return2.json |  7 ++
>  tests/qapi-schema/doc-invalid-return2.out  |  0
>  tests/qapi-schema/meson.build              |  1 +
>  29 files changed, 189 insertions(+), 245 deletions(-)
>  create mode 100644 tests/qapi-schema/doc-invalid-return2.err
>  create mode 100644 tests/qapi-schema/doc-invalid-return2.json
>  create mode 100644 tests/qapi-schema/doc-invalid-return2.out
>
> --
> 2.43.0
>
>