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>

12 files changed, 47 insertions, 38 deletions

diff --git a/qapi/block-core.json b/qapi/block-core.json
index eeb2ed3f16..a5a5007b28 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 5fe068f903..94339a1761 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 923dc5056d..c9431dd0a7 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 8c3c58c763..20541cb319 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 91c1773739..015b22c970 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 7e278ca1eb..4afaee7fe7 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 d6eb30008b..1f1e148f01 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 2708fb4e99..f309facf8d 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 4fe7a93a75..2a3891e3cb 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 729470300d..fcbf10e237 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 419c188dd1..bfc15ecad5 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 2fa41c8ab0..fa05bc1365 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.
 #