aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorMarkus Armbruster <armbru@redhat.com>2023-04-25 08:42:14 +0200
committerMarkus Armbruster <armbru@redhat.com>2023-04-28 11:48:34 +0200
commit37fa48a4cbd68760235293ebf95980fb87239b42 (patch)
treea2c7859d90cd2d77044b4c895071ab3df69ae54a
parentf1a787b5f4b60524580ed9d1527568590d73789b (diff)
downloadqemu-37fa48a4cbd68760235293ebf95980fb87239b42.zip
qemu-37fa48a4cbd68760235293ebf95980fb87239b42.tar.gz
qemu-37fa48a4cbd68760235293ebf95980fb87239b42.tar.bz2
qapi: Tidy up examples
A few examples neglect to prefix QMP input with '->'. Fix that. Two examples have extra space after '<-'. Delete it. A few examples neglect to show output. Provide some. The example output for query-vcpu-dirty-limit could use further improvement. Add a TODO comment. Use "Examples:" instead of "Example:" where multiple examples are given. One example section numbers its two examples. Not done elsewhere; drop. Another example section separates them with "or". Likewise. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Message-Id: <20230425064223.820979-8-armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com>
-rw-r--r--qapi/block-core.json14
-rw-r--r--qapi/block.json2
-rw-r--r--qapi/char.json4
-rw-r--r--qapi/machine.json7
-rw-r--r--qapi/migration.json33
-rw-r--r--qapi/misc.json7
-rw-r--r--qapi/net.json4
-rw-r--r--qapi/qdev.json2
-rw-r--r--qapi/qom.json2
-rw-r--r--qapi/replay.json3
-rw-r--r--qapi/run-state.json5
-rw-r--r--qapi/ui.json2
12 files changed, 47 insertions, 38 deletions
diff --git a/qapi/block-core.json b/qapi/block-core.json
index eeb2ed3..a5a5007 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -4574,9 +4574,8 @@
#
# Since: 2.9
#
-# Example:
+# Examples:
#
-# 1.
# -> { "execute": "blockdev-add",
# "arguments": {
# "driver": "qcow2",
@@ -4589,7 +4588,6 @@
# }
# <- { "return": {} }
#
-# 2.
# -> { "execute": "blockdev-add",
# "arguments": {
# "driver": "qcow2",
@@ -5596,7 +5594,7 @@
#
# Since: 2.7
#
-# Example:
+# Examples:
#
# 1. Add a new node to a quorum
# -> { "execute": "blockdev-add",
@@ -5646,7 +5644,7 @@
#
# Since: 2.12
#
-# Example:
+# Examples:
#
# 1. Move a node into an IOThread
# -> { "execute": "x-blockdev-set-iothread",
@@ -5731,18 +5729,18 @@
#
# Since: 2.0
#
-# Example:
+# Examples:
#
# 1. Read operation
#
-# { "event": "QUORUM_REPORT_BAD",
+# <- { "event": "QUORUM_REPORT_BAD",
# "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
# "type": "read" },
# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
#
# 2. Flush operation
#
-# { "event": "QUORUM_REPORT_BAD",
+# <- { "event": "QUORUM_REPORT_BAD",
# "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
# "type": "flush", "error": "Broken pipe" },
# "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
diff --git a/qapi/block.json b/qapi/block.json
index 5fe068f..94339a1 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -457,7 +457,7 @@
#
# Since: 1.1
#
-# Example:
+# Examples:
#
# -> { "execute": "block_set_io_throttle",
# "arguments": { "id": "virtio-blk-pci0/virtio-backend",
diff --git a/qapi/char.json b/qapi/char.json
index 923dc50..c9431dd 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -637,7 +637,7 @@
#
# Since: 1.4
#
-# Example:
+# Examples:
#
# -> { "execute" : "chardev-add",
# "arguments" : { "id" : "foo",
@@ -673,7 +673,7 @@
#
# Since: 2.10
#
-# Example:
+# Examples:
#
# -> { "execute" : "chardev-change",
# "arguments" : { "id" : "baz",
diff --git a/qapi/machine.json b/qapi/machine.json
index 8c3c58c..20541cb 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -954,7 +954,7 @@
#
# Since: 2.7
#
-# Example:
+# Examples:
#
# For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:
#
@@ -1677,8 +1677,9 @@
# Since: 7.2
#
# Example:
-# {"execute": "dumpdtb"}
-# "arguments": { "filename": "fdt.dtb" } }
+# -> { "execute": "dumpdtb" }
+# "arguments": { "filename": "fdt.dtb" } }
+# <- { "return": {} }
#
##
{ 'command': 'dumpdtb',
diff --git a/qapi/migration.json b/qapi/migration.json
index 91c17737..015b22c 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -273,7 +273,7 @@
#
# Since: 0.14
#
-# Example:
+# Examples:
#
# 1. Before the first migration
#
@@ -521,6 +521,7 @@
#
# -> { "execute": "migrate-set-capabilities" , "arguments":
# { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
+# <- { "return": {} }
#
##
{ 'command': 'migrate-set-capabilities',
@@ -989,6 +990,7 @@
#
# -> { "execute": "migrate-set-parameters" ,
# "arguments": { "compress-level": 1 } }
+# <- { "return": {} }
#
##
{ 'command': 'migrate-set-parameters', 'boxed': true,
@@ -1251,8 +1253,8 @@
#
# Example:
#
-# { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
-# "event": "MIGRATION_PASS", "data": {"pass": 2} }
+# <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
+# "event": "MIGRATION_PASS", "data": {"pass": 2} }
#
##
{ 'event': 'MIGRATION_PASS',
@@ -1833,8 +1835,9 @@
#
# Example:
#
-# {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1,
-# 'sample-pages': 512} }
+# -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1,
+# 'sample-pages': 512} }
+# <- { "return": {} }
#
##
{ 'command': 'calc-dirty-rate', 'data': {'calc-time': 'int64',
@@ -1886,9 +1889,11 @@
# Since: 7.1
#
# Example:
-# {"execute": "set-vcpu-dirty-limit"}
-# "arguments": { "dirty-rate": 200,
-# "cpu-index": 1 } }
+#
+# -> {"execute": "set-vcpu-dirty-limit"}
+# "arguments": { "dirty-rate": 200,
+# "cpu-index": 1 } }
+# <- { "return": {} }
#
##
{ 'command': 'set-vcpu-dirty-limit',
@@ -1909,8 +1914,10 @@
# Since: 7.1
#
# Example:
-# {"execute": "cancel-vcpu-dirty-limit"}
-# "arguments": { "cpu-index": 1 } }
+#
+# -> {"execute": "cancel-vcpu-dirty-limit"},
+# "arguments": { "cpu-index": 1 } }
+# <- { "return": {} }
#
##
{ 'command': 'cancel-vcpu-dirty-limit',
@@ -1924,7 +1931,11 @@
# Since: 7.1
#
# Example:
-# {"execute": "query-vcpu-dirty-limit"}
+#
+# -> {"execute": "query-vcpu-dirty-limit"}
+# <- {"return": [
+# { "limit-rate": 60, "current-rate": 3, "cpu-index": 0},
+# { "limit-rate": 60, "current-rate": 3, "cpu-index": 1}]}
#
##
{ 'command': 'query-vcpu-dirty-limit',
diff --git a/qapi/misc.json b/qapi/misc.json
index 7e278ca..4afaee7 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -580,10 +580,9 @@
#
# Example:
#
-# <- { "event": "RTC_CHANGE",
-# "data": { "offset": 78 },
-# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
-#
+# <- { "event": "RTC_CHANGE",
+# "data": { "offset": 78 },
+# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
##
{ 'event': 'RTC_CHANGE',
'data': { 'offset': 'int', 'qom-path': 'str' } }
diff --git a/qapi/net.json b/qapi/net.json
index d6eb300..1f1e148 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -914,7 +914,7 @@
#
# Since: 7.2
#
-# Example:
+# Examples:
#
# <- { "event": "NETDEV_STREAM_CONNECTED",
# "data": { "netdev-id": "netdev0",
@@ -922,8 +922,6 @@
# "host": "::1", "type": "inet" } },
# "timestamp": { "seconds": 1666269863, "microseconds": 311222 } }
#
-# or
-#
# <- { "event": "NETDEV_STREAM_CONNECTED",
# "data": { "netdev-id": "netdev0",
# "addr": { "path": "/tmp/qemu0", "type": "unix" } },
diff --git a/qapi/qdev.json b/qapi/qdev.json
index 2708fb4..f309fac 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -100,7 +100,7 @@
#
# Since: 0.14
#
-# Example:
+# Examples:
#
# -> { "execute": "device_del",
# "arguments": { "id": "net1" } }
diff --git a/qapi/qom.json b/qapi/qom.json
index 4fe7a93..2a3891e 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -103,7 +103,7 @@
#
# Since: 1.2
#
-# Example:
+# Examples:
#
# 1. Use absolute path
#
diff --git a/qapi/replay.json b/qapi/replay.json
index 7294703..fcbf10e 100644
--- a/qapi/replay.json
+++ b/qapi/replay.json
@@ -81,6 +81,7 @@
# Example:
#
# -> { "execute": "replay-break", "arguments": { "icount": 220414 } }
+# <- { "return": {} }
#
##
{ 'command': 'replay-break', 'data': { 'icount': 'int' } }
@@ -96,6 +97,7 @@
# Example:
#
# -> { "execute": "replay-delete-break" }
+# <- { "return": {} }
#
##
{ 'command': 'replay-delete-break' }
@@ -117,5 +119,6 @@
# Example:
#
# -> { "execute": "replay-seek", "arguments": { "icount": 220414 } }
+# <- { "return": {} }
##
{ 'command': 'replay-seek', 'data': { 'icount': 'int' } }
diff --git a/qapi/run-state.json b/qapi/run-state.json
index 419c188..bfc15ec 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -258,9 +258,8 @@
#
# Example:
#
-# <- { "event": "SUSPEND_DISK",
-# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
-#
+# <- { "event": "SUSPEND_DISK",
+# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
##
{ 'event': 'SUSPEND_DISK' }
diff --git a/qapi/ui.json b/qapi/ui.json
index 2fa41c8..fa05bc1 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -1153,7 +1153,7 @@
# so it is possible to map which console belongs to which device and
# display.
#
-# Example:
+# Examples:
#
# 1. Press left mouse button.
#