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