@@ -5913,35 +5913,31 @@
##
# @x-blockdev-change:
#
-# Dynamically reconfigure the block driver state graph. It can be
-# used to add, remove, insert or replace a graph node. Currently only
-# the Quorum driver implements this feature to add or remove its
-# child. This is useful to fix a broken quorum child.
+# Dynamically reconfigure the block driver state graph.
#
-# If @node is specified, it will be inserted under @parent. @child
-# may not be specified in this case. If both @parent and @child are
-# specified but @node is not, @child will be detached from @parent.
+# Currently only supports adding and deleting quorum children. A
+# child will be added at the end of the list of children. Its
+# contents *must* be consistent with the other childrens' contents.
+# Deleting a child that is not last in the list of children is
+# problematic, because it "renumbers" the children following it.
#
# @parent: the id or name of the parent node.
#
-# @child: the name of a child under the given parent node.
+# @child: the name of a child to be deleted. Mutually exclusive with
+# @node.
#
-# @node: the name of the node that will be added.
+# @node: the name of the node to be added. Mutually exclusive with
+# @child.
#
# Features:
#
-# @unstable: This command is experimental, and its API is not stable.
-# It does not support all kinds of operations, all kinds of
-# children, nor all block drivers.
+# @unstable: This command is experimental.
#
-# FIXME Removing children from a quorum node means introducing
+# TODO: Removing children from a quorum node means introducing
# gaps in the child indices. This cannot be represented in the
# 'children' list of BlockdevOptionsQuorum, as returned by
# .bdrv_refresh_filename().
#
-# Warning: The data in a new quorum child MUST be consistent with
-# that of the rest of the array.
-#
# Since: 2.7
#
# .. qmp-example::
The description of feature @unstable is three paragraphs. The second and third became part of the description by accident in commit 9fb49daabfb (qapi: Mark unstable QMP parts with feature 'unstable'). The second paragraph describes a defect in terms of the implementation. Fine, but doesn't belong into user-facing documentation. Turn it into a TODO section. Rewrite everything else for clarity and completeness. Signed-off-by: Markus Armbruster <armbru@redhat.com> --- qapi/block-core.json | 28 ++++++++++++---------------- 1 file changed, 12 insertions(+), 16 deletions(-)