* [PATCH 0/2] qapi: Remove some error documentation lint
@ 2024-09-11 13:24 Markus Armbruster
2024-09-11 13:24 ` [PATCH 1/2] qapi: Drop "with an explanation" from error descriptions Markus Armbruster
` (2 more replies)
0 siblings, 3 replies; 6+ messages in thread
From: Markus Armbruster @ 2024-09-11 13:24 UTC (permalink / raw)
To: qemu-devel; +Cc: kwolf, hreitz, eblake, qemu-block, jsnow
Markus Armbruster (2):
qapi: Drop "with an explanation" from error descriptions
qapi/block-core: Drop drive-backup's "Any other error" documentation
qapi/block-core.json | 12 +++++-------
1 file changed, 5 insertions(+), 7 deletions(-)
--
2.46.0
^ permalink raw reply [flat|nested] 6+ messages in thread* [PATCH 1/2] qapi: Drop "with an explanation" from error descriptions 2024-09-11 13:24 [PATCH 0/2] qapi: Remove some error documentation lint Markus Armbruster @ 2024-09-11 13:24 ` Markus Armbruster 2024-09-12 12:59 ` Eric Blake 2024-09-11 13:24 ` [PATCH 2/2] qapi/block-core: Drop drive-backup's "Any other error" documentation Markus Armbruster 2024-09-13 8:09 ` [PATCH 0/2] qapi: Remove some error documentation lint Markus Armbruster 2 siblings, 1 reply; 6+ messages in thread From: Markus Armbruster @ 2024-09-11 13:24 UTC (permalink / raw) To: qemu-devel; +Cc: kwolf, hreitz, eblake, qemu-block, jsnow All errors come with an explanation, namely the human-readable error message in the error response's @desc member. Drop the redundant "with an explanation" phrase. Signed-off-by: Markus Armbruster <armbru@redhat.com> --- qapi/block-core.json | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 9f6dd59298..82f59a7758 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -2299,7 +2299,7 @@ # # Errors: # - If @node is not a valid block device or node, DeviceNotFound -# - If @name is already taken, GenericError with an explanation +# - If @name is already taken, GenericError # # Since: 2.4 # @@ -2322,7 +2322,7 @@ # # Errors: # - If @node is not a valid block device or node, DeviceNotFound -# - If @name is not found, GenericError with an explanation +# - If @name is not found, GenericError # - if @name is frozen by an operation, GenericError # # Since: 2.4 @@ -2346,7 +2346,7 @@ # # Errors: # - If @node is not a valid block device, DeviceNotFound -# - If @name is not found, GenericError with an explanation +# - If @name is not found, GenericError # # Since: 2.4 # @@ -2367,7 +2367,7 @@ # # Errors: # - If @node is not a valid block device, DeviceNotFound -# - If @name is not found, GenericError with an explanation +# - If @name is not found, GenericError # # Since: 4.0 # @@ -2388,7 +2388,7 @@ # # Errors: # - If @node is not a valid block device, DeviceNotFound -# - If @name is not found, GenericError with an explanation +# - If @name is not found, GenericError # # Since: 4.0 # @@ -2462,7 +2462,6 @@ # Errors: # - If @node is not a valid block device, DeviceNotFound # - If @name is not found or if hashing has failed, GenericError -# with an explanation # # Since: 2.10 ## -- 2.46.0 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH 1/2] qapi: Drop "with an explanation" from error descriptions 2024-09-11 13:24 ` [PATCH 1/2] qapi: Drop "with an explanation" from error descriptions Markus Armbruster @ 2024-09-12 12:59 ` Eric Blake 0 siblings, 0 replies; 6+ messages in thread From: Eric Blake @ 2024-09-12 12:59 UTC (permalink / raw) To: Markus Armbruster; +Cc: qemu-devel, kwolf, hreitz, qemu-block, jsnow On Wed, Sep 11, 2024 at 03:24:58PM GMT, Markus Armbruster wrote: > All errors come with an explanation, namely the human-readable error > message in the error response's @desc member. Drop the redundant > "with an explanation" phrase. > > Signed-off-by: Markus Armbruster <armbru@redhat.com> > --- > qapi/block-core.json | 11 +++++------ > 1 file changed, 5 insertions(+), 6 deletions(-) Reviewed-by: Eric Blake <eblake@redhat.com> -- Eric Blake, Principal Software Engineer Red Hat, Inc. Virtualization: qemu.org | libguestfs.org ^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH 2/2] qapi/block-core: Drop drive-backup's "Any other error" documentation 2024-09-11 13:24 [PATCH 0/2] qapi: Remove some error documentation lint Markus Armbruster 2024-09-11 13:24 ` [PATCH 1/2] qapi: Drop "with an explanation" from error descriptions Markus Armbruster @ 2024-09-11 13:24 ` Markus Armbruster 2024-09-12 12:59 ` Eric Blake 2024-09-13 8:09 ` [PATCH 0/2] qapi: Remove some error documentation lint Markus Armbruster 2 siblings, 1 reply; 6+ messages in thread From: Markus Armbruster @ 2024-09-11 13:24 UTC (permalink / raw) To: qemu-devel; +Cc: kwolf, hreitz, eblake, qemu-block, jsnow We've always been rather lax about documenting errors. Many "Errors" sections are obviously not exhaustive. Only drive-backup is explicit about this: "Any other error returns a GenericError". Not useful. Drop. Signed-off-by: Markus Armbruster <armbru@redhat.com> --- qapi/block-core.json | 1 - 1 file changed, 1 deletion(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 82f59a7758..485388be32 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -1853,7 +1853,6 @@ # # Errors: # - If @device does not exist, DeviceNotFound -# - Any other error returns a GenericError. # # Since: 1.3 # -- 2.46.0 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH 2/2] qapi/block-core: Drop drive-backup's "Any other error" documentation 2024-09-11 13:24 ` [PATCH 2/2] qapi/block-core: Drop drive-backup's "Any other error" documentation Markus Armbruster @ 2024-09-12 12:59 ` Eric Blake 0 siblings, 0 replies; 6+ messages in thread From: Eric Blake @ 2024-09-12 12:59 UTC (permalink / raw) To: Markus Armbruster; +Cc: qemu-devel, kwolf, hreitz, qemu-block, jsnow On Wed, Sep 11, 2024 at 03:24:59PM GMT, Markus Armbruster wrote: > We've always been rather lax about documenting errors. Many "Errors" > sections are obviously not exhaustive. Only drive-backup is explicit > about this: "Any other error returns a GenericError". > > Not useful. Drop. > > Signed-off-by: Markus Armbruster <armbru@redhat.com> > --- > qapi/block-core.json | 1 - > 1 file changed, 1 deletion(-) Reviewed-by: Eric Blake <eblake@redhat.com> > > diff --git a/qapi/block-core.json b/qapi/block-core.json > index 82f59a7758..485388be32 100644 > --- a/qapi/block-core.json > +++ b/qapi/block-core.json > @@ -1853,7 +1853,6 @@ > # > # Errors: > # - If @device does not exist, DeviceNotFound > -# - Any other error returns a GenericError. > # > # Since: 1.3 > # > -- > 2.46.0 > -- Eric Blake, Principal Software Engineer Red Hat, Inc. Virtualization: qemu.org | libguestfs.org ^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH 0/2] qapi: Remove some error documentation lint 2024-09-11 13:24 [PATCH 0/2] qapi: Remove some error documentation lint Markus Armbruster 2024-09-11 13:24 ` [PATCH 1/2] qapi: Drop "with an explanation" from error descriptions Markus Armbruster 2024-09-11 13:24 ` [PATCH 2/2] qapi/block-core: Drop drive-backup's "Any other error" documentation Markus Armbruster @ 2024-09-13 8:09 ` Markus Armbruster 2 siblings, 0 replies; 6+ messages in thread From: Markus Armbruster @ 2024-09-13 8:09 UTC (permalink / raw) To: qemu-devel; +Cc: kwolf, hreitz, eblake, qemu-block, jsnow Queued. ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2024-09-13 8:10 UTC | newest] Thread overview: 6+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2024-09-11 13:24 [PATCH 0/2] qapi: Remove some error documentation lint Markus Armbruster 2024-09-11 13:24 ` [PATCH 1/2] qapi: Drop "with an explanation" from error descriptions Markus Armbruster 2024-09-12 12:59 ` Eric Blake 2024-09-11 13:24 ` [PATCH 2/2] qapi/block-core: Drop drive-backup's "Any other error" documentation Markus Armbruster 2024-09-12 12:59 ` Eric Blake 2024-09-13 8:09 ` [PATCH 0/2] qapi: Remove some error documentation lint Markus Armbruster
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).