diff options
| author | Markus Armbruster <armbru@redhat.com> | 2025-05-27 09:39:16 +0200 |
|---|---|---|
| committer | Markus Armbruster <armbru@redhat.com> | 2025-06-03 08:34:57 +0200 |
| commit | 8fa2020647041e9f01bc308589bb7fa00355ac9b (patch) | |
| tree | 4c9d62677114a6f9078abece7df722af509b08a6 | |
| parent | feeb08c260171e8a15236d20f2978c68aae4f569 (diff) | |
| download | qemu-8fa2020647041e9f01bc308589bb7fa00355ac9b.zip qemu-8fa2020647041e9f01bc308589bb7fa00355ac9b.tar.gz qemu-8fa2020647041e9f01bc308589bb7fa00355ac9b.tar.bz2 | |
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>
| -rw-r--r-- | qapi/block-core.json | 19 | ||||
| -rw-r--r-- | qapi/job.json | 2 |
2 files changed, 8 insertions, 13 deletions
diff --git a/qapi/block-core.json b/qapi/block-core.json index da390f8..1df6644 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 441cd77..126fa5c 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 |