On Wed, Jun 19, 2024, 8:10 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@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 <js...@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 <arm...@redhat.com> > okie dokie. (Feel free to adjust the doc phrasing too, if you want. I promise I'm not offended by that.) >
