[v1] qapi: convert "Note" and "Example" sections to rST

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

Posted by John Snow 1 year, 5 months ago

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>
---
 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
-- 
2.44.0

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

Posted by Markus Armbruster 1 year, 5 months ago

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>

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

Posted by John Snow 1 year, 5 months ago

On Wed, Jun 19, 2024, 8:10 AM Markus Armbruster <armbru@redhat.com> wrote:

> 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.)

>