diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index 7194ab1e2b..116d2f723c 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -219,26 +219,6 @@ Example:
      "arguments": { "enable": true } }
 <- { "return": {} }
 
-migrate-incoming
-----------------
-
-Continue an incoming migration
-
-Arguments:
-
-- "uri": Source/listening URI (json-string)
-
-Example:
-
--> { "execute": "migrate-incoming", "arguments": { "uri": "tcp::4446" } }
-<- { "return": {} }
-
-Notes:
-
-(1) QEMU must be started with -incoming defer to allow migrate-incoming to
-    be used
-(2) The uri format is the same as for -incoming
-
 migrate-set-cache-size
 ----------------------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index ef27197460..f021cd0dfc 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -3005,9 +3005,24 @@
 # Returns: nothing on success
 #
 # Since: 2.3
-# Note: It's a bad idea to use a string for the uri, but it needs to stay
-# compatible with -incoming and the format of the uri is already exposed
-# above libvirt
+#
+# Notes:
+#
+# 1. It's a bad idea to use a string for the uri, but it needs to stay
+#    compatible with -incoming and the format of the uri is already exposed
+#    above libvirt.
+#
+# 2. QEMU must be started with -incoming defer to allow migrate-incoming to
+#    be used.
+#
+# 3. The uri format is the same as for -incoming
+#
+# Example:
+#
+# -> { "execute": "migrate-incoming",
+#      "arguments": { "uri": "tcp::4446" } }
+# <- { "return": {} }
+#
 ##
 { 'command': 'migrate-incoming', 'data': {'uri': 'str' } }