diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt
index d018480a28..9445bd1349 100644
--- a/docs/qmp-commands.txt
+++ b/docs/qmp-commands.txt
@@ -2193,25 +2193,6 @@ Example:
      ]
    }
 
-query-balloon
--------------
-
-Show balloon information.
-
-Make an asynchronous request for balloon info. When the request completes a
-json-object will be returned containing the following data:
-
-- "actual": current balloon value in bytes (json-int)
-
-Example:
-
--> { "execute": "query-balloon" }
-<- {
-      "return":{
-         "actual":1073741824,
-      }
-   }
-
 query-tpm
 ---------
 
diff --git a/qapi-schema.json b/qapi-schema.json
index 93e376b90a..f47d50c182 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -1793,11 +1793,22 @@
 # Return information about the balloon device.
 #
 # Returns: @BalloonInfo on success
+#
 #          If the balloon driver is enabled but not functional because the KVM
 #          kernel module cannot support it, KvmMissingCap
+#
 #          If no balloon device is present, DeviceNotActive
 #
 # Since: 0.14.0
+#
+# Example:
+#
+# -> { "execute": "query-balloon" }
+# <- { "return": {
+#          "actual": 1073741824,
+#       }
+#    }
+#
 ##
 { 'command': 'query-balloon', 'returns': 'BalloonInfo' }