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>
okie dokie.
(Feel free to adjust the doc phrasing too, if you want. I promise I'm not offended by that.)