* [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
* [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 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
* 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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.