qapi: Improve documentation around job state @concluded

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>

diff --git a/qapi/block-core.json b/qapi/block-core.json
index da390f85acf6660c9d542998d0bea039d584e916..1df6644f0de286f629d70360ad91b9715f794644 100644 (file)
--- 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 441cd7772b3d505b8e6e8476e5527b4d11fab78f..126fa5ce6021d3bf7e66f517fa61b19173851adf 100644 (file)
--- 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