diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 70de4a60670d4ac63d8684cdb0b3a143ab781e9b..af903bff2636207eaac3dace813ceb786f1099ee 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -438,25 +438,6 @@ Example:
 -> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } }
 <- { "return": {} }
 
-block-set-write-threshold
-------------
-
-Change the write threshold for a block drive. The threshold is an offset,
-thus must be non-negative. Default is no write threshold.
-Setting the threshold to zero disables it.
-
-Arguments:
-
-- "node-name": the node name in the block driver state graph (json-string)
-- "write-threshold": the write threshold in bytes (json-int)
-
-Example:
-
--> { "execute": "block-set-write-threshold",
-  "arguments": { "node-name": "mydev",
-                 "write-threshold": 17179869184 } }
-<- { "return": {} }
-
 Show rocker switch
 ------------------
 
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 0f8aacdfd03526985dc16170bb41008c38b1ac6f..40b5e1ba8ba5f5f66c39dcd755237a22c968a0c4 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -3402,8 +3402,12 @@
 ##
 # @block-set-write-threshold:
 #
-# Change the write threshold for a block drive. An event will be delivered
-# if a write to this block drive crosses the configured threshold.
+# Change the write threshold for a block drive. An event will be
+# delivered if a write to this block drive crosses the configured
+# threshold.  The threshold is an offset, thus must be
+# non-negative. Default is no write threshold. Setting the threshold
+# to zero disables it.
+#
 # This is useful to transparently resize thin-provisioned drives without
 # the guest OS noticing.
 #
@@ -3413,6 +3417,14 @@
 #                   Use 0 to disable the threshold.
 #
 # Since: 2.3
+#
+# Example:
+#
+# -> { "execute": "block-set-write-threshold",
+#      "arguments": { "node-name": "mydev",
+#                     "write-threshold": 17179869184 } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'block-set-write-threshold',
   'data': { 'node-name': 'str', 'write-threshold': 'uint64' } }