Re: [PATCH 08/13] qapi: ensure all errors sections are uniformly typset

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> Transactions have the only instance of an Errors section that isn't a
> rST list; turn it into one.
>
> Signed-off-by: John Snow <jsnow@redhat.com>

Let;s explain the "why" a bit more clearly.  Maybe

    qapi: Nail down convention that Errors sections are lists

    By unstated convention, Errors sections are rST lists.  Document the
    convention, and make the one exception conform.

> ---
>  docs/devel/qapi-code-gen.rst | 7 +++++++
>  qapi/transaction.json        | 2 +-
>  2 files changed, 8 insertions(+), 1 deletion(-)
>
> diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
> index f453bd35465..cee43222f19 100644
> --- a/docs/devel/qapi-code-gen.rst
> +++ b/docs/devel/qapi-code-gen.rst
> @@ -1011,6 +1011,13 @@ like this::
>  "Returns" and "Errors" sections are only valid for commands.  They
>  document the success and the error response, respectively.
>  
> +"Errors" sections should be formatted as an rST list, each entry
> +detailing a relevant error condition. For example::
> +
> + # Errors:
> + #     - If @device does not exist, DeviceNotFound
> + #     - Any other error returns a GenericError.
> +
>  A "Since: x.y.z" tagged section lists the release that introduced the
>  definition.
>  
> diff --git a/qapi/transaction.json b/qapi/transaction.json
> index 5749c133d4a..07afc269d54 100644
> --- a/qapi/transaction.json
> +++ b/qapi/transaction.json
> @@ -235,7 +235,7 @@
>  #     additional detail.
>  #
>  # Errors:
> -#     Any errors from commands in the transaction
> +#     - Any errors from commands in the transaction
>  #
>  # Note: The transaction aborts on the first failure.  Therefore, there
>  #     will be information on only one failed operation returned in an

Preferably with an improved commit message
Reviewed-by: Markus Armbruster <armbru@redhat.com>