We use "the query list" in a few places. It's not entirely obvious
what that means. It's actually the output of query-jobs or
query-block-jobs.
Documentation of @auto-dismiss talks about the job disappearing from
the query list when it reaches state @concluded. This is less than
precise. The job doesn't merely disappear from the query list, it
disappears, period.
Documentation of JobStatus @concluded explains "the job will remain in
the query list until it is dismissed". Again less than precise. It
remains in state @concluded until dismissed.
Rephrase without use of "the query list" for clarity and precision.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20250527073916.1243024-14-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
---
qapi/block-core.json | 19 +++++++------------
qapi/job.json | 2 +-
2 files changed, 8 insertions(+), 13 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index da390f85ac..1df6644f0d 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1417,8 +1417,8 @@
# @auto-finalize: Job will finalize itself when PENDING, moving to the
# CONCLUDED state. (since 2.12)
#
-# @auto-dismiss: Job will dismiss itself when CONCLUDED, moving to the
-# NULL state and disappearing from the query list. (since 2.12)
+# @auto-dismiss: Job will dismiss itself when CONCLUDED, and
+# disappear. (since 2.12)
#
# @error: Error information if the job did not complete successfully.
# Not set if the job completed successfully. (since 2.12.1)
@@ -1614,8 +1614,7 @@
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear
-# from the query list without user intervention. Defaults to
-# true. (Since 2.12)
+# without user intervention. Defaults to true. (Since 2.12)
#
# @filter-node-name: the node name that should be assigned to the
# filter driver that the backup job inserts into the graph above
@@ -1855,8 +1854,7 @@
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear
-# from the query list without user intervention. Defaults to
-# true. (Since 3.1)
+# without user intervention. Defaults to true. (Since 3.1)
#
# Features:
#
@@ -2219,8 +2217,7 @@
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear
-# from the query list without user intervention. Defaults to
-# true. (Since 3.1)
+# without user intervention. Defaults to true. (Since 3.1)
#
# Since: 1.3
##
@@ -2538,8 +2535,7 @@
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear
-# from the query list without user intervention. Defaults to
-# true. (Since 3.1)
+# without user intervention. Defaults to true. (Since 3.1)
#
# @target-is-zero: Assume the destination reads as all zeroes before
# the mirror started. Setting this to true can speed up the
@@ -2866,8 +2862,7 @@
# @auto-dismiss: When false, this job will wait in a CONCLUDED state
# after it has completely ceased all work, and awaits
# @job-dismiss. When true, this job will automatically disappear
-# from the query list without user intervention. Defaults to
-# true. (Since 3.1)
+# without user intervention. Defaults to true. (Since 3.1)
#
# Errors:
# - If @device does not exist, DeviceNotFound.
diff --git a/qapi/job.json b/qapi/job.json
index 441cd7772b..126fa5ce60 100644
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -74,7 +74,7 @@
# process.
#
# @concluded: The job has finished all work. If auto-dismiss was set
-# to false, the job will remain in the query list until it is
+# to false, the job will remain in this state until it is
# dismissed via @job-dismiss.
#
# @null: The job is in the process of being dismantled. This state
--
2.48.1