Skip to contentSkip to conversation

qapi-block-core: Clean up blockdev-snapshot-internal-sync doc

PATCH Applied Markus Armbruster 2 participants 2 messages Jul 18, 2024

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 qapi-block-core: Clean up blockdev-snapshot-internal-sync doc

BlockdevSnapshotInternal is the arguments type of command blockdev-snapshot-internal-sync. Its doc comment contains this note:

    # .. note:: In a transaction, if @name is empty or any snapshot matching
    #    @name exists, the operation will fail.  Only some image formats
    #    support it; for example, qcow2, and rbd.

"In a transaction" is misleading, and "if @name is empty or any snapshot matching @name exists, the operation will fail" is redundant with the command's Errors documentation. Drop.

The remainder is fine. Move it to the command's doc comment, where it is more prominently visible, with a slight rephrasing for clarity.

---
 qapi/block-core.json | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)
qapi/block-core.json +3 -4
index f400b334c8..994e384a71 100644
@@ -6046,10 +6046,6 @@
 #
 # @name: the name of the internal snapshot to be created
 #
-# .. note:: In a transaction, if @name is empty or any snapshot matching
-#    @name exists, the operation will fail.  Only some image formats
-#    support it; for example, qcow2, and rbd.
-#
 # Since: 1.7
 ##
 { 'struct': 'BlockdevSnapshotInternal',
@@ -6070,6 +6066,9 @@
 #     - If the format of the image used does not support it,
 #       GenericError
 #
+# .. note:: Only some image formats such as qcow2 and rbd support
+#    internal snapshots.
+#
 # Since: 1.7
 #
 # .. qmp-example::
Signature · 1 line
2.45.0
Applied
#1 lore raw

Am 18.07.2024 um 14:36 hat Markus Armbruster geschrieben:

Quoted 7 lines

BlockdevSnapshotInternal is the arguments type of command blockdev-snapshot-internal-sync. Its doc comment contains this note:

    # .. note:: In a transaction, if @name is empty or any snapshot matching
    #    @name exists, the operation will fail.  Only some image formats
    #    support it; for example, qcow2, and rbd.
Quoted 8 lines

"In a transaction" is misleading, and "if @name is empty or any snapshot matching @name exists, the operation will fail" is redundant with the command's Errors documentation. Drop.

The remainder is fine. Move it to the command's doc comment, where it is more prominently visible, with a slight rephrasing for clarity.

Thanks, applied to the block branch.

Kevin