On 07.04.25 18:28, Eric Blake wrote:
On Fri, Apr 04, 2025 at 10:31:53PM +0300, Vladimir Sementsov-Ogievskiy wrote:
Actualize documentation and synchronize it for commands which actually
call the same functions internally.
Signed-off-by: Vladimir Sementsov-Ogievskiy <vsement...@yandex-team.ru>
---
qapi/block-core.json | 59 +++++++++++++++++++++++++-------------------
qapi/job.json | 29 ++++++++++++++++++++--
2 files changed, 61 insertions(+), 27 deletions(-)
Overall makes sense, but one thing jumped out at me:
# @block-job-complete:
#
-# Manually trigger completion of an active background block operation.
-# This is supported for drive mirroring, where it also switches the
-# device to write to the target path only. The ability to complete is
-# signaled with a BLOCK_JOB_READY event.
+# Manually trigger completion of an active job in the READY or STANDBY
+# state. Completing the job in any other state is an error.
+#
+# This is supported only for drive mirroring (which includes
+# drive-mirror, blockdev-mirror and block-commit job (only in case of
+# "active commit", when the node being commited is used by the guest)),
+# where it also switches the device to write to the target path only.
The doubly-nested parenthetical feels long. Is there a more concise
way of expressing the list of three commands, where one of the
commands only supports it in the special case of "active commit"?
Probably, move the big "(...)" to the second sentence:
Note that drive mirroring includes [...] the guest).
--
Best regards,
Vladimir
