mbox series

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

Message ID 20240227113921.236097-1-armbru@redhat.com (mailing list archive)
Headers show
Series Subject: [PATCH 00/15] qapi: Improve command response documentation | expand

Message

Markus Armbruster Feb. 27, 2024, 11:39 a.m. UTC
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

Comments

Konstantin Kostiuk March 11, 2024, 3:37 p.m. UTC | #1
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
>
>