| Message ID | 20240619003012.1753577-9-jsnow@redhat.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | qapi: convert "Note" and "Example" sections to rST | expand |
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>
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.) >
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
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(-)