From: Markus Armbruster <armbru@redhat.com>
To: qemu-devel@nongnu.org
Cc: michael.roth@amd.com, eblake@redhat.com, kwolf@redhat.com,
hreitz@redhat.com, pbonzini@redhat.com,
marcandre.lureau@redhat.com, arei.gonglei@huawei.com,
pizhenwei@bytedance.com, jsnow@redhat.com,
vsementsov@yandex-team.ru, eduardo@habkost.net,
marcel.apfelbaum@gmail.com, wangyanan55@huawei.com,
quintela@redhat.com, jasowang@redhat.com,
yuval.shaia.ml@gmail.com, stefanha@redhat.com, kraxel@redhat.com,
kkostiuk@redhat.com, qemu-block@nongnu.org,
marcandre.lureau@gmail.com, david@redhat.com
Subject: [PATCH v2 07/16] qapi: Tidy up examples
Date: Tue, 25 Apr 2023 08:42:14 +0200 [thread overview]
Message-ID: <20230425064223.820979-8-armbru@redhat.com> (raw)
In-Reply-To: <20230425064223.820979-1-armbru@redhat.com>
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>
---
qapi/block-core.json | 14 ++++++--------
qapi/block.json | 2 +-
qapi/char.json | 4 ++--
qapi/machine.json | 7 ++++---
qapi/migration.json | 33 ++++++++++++++++++++++-----------
qapi/misc.json | 7 +++----
qapi/net.json | 4 +---
qapi/qdev.json | 2 +-
qapi/qom.json | 2 +-
qapi/replay.json | 3 +++
qapi/run-state.json | 5 ++---
qapi/ui.json | 2 +-
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 87c174dca2..477ee4d35b 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,
@@ -1279,8 +1281,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',
@@ -1861,8 +1863,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',
@@ -1914,9 +1917,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',
@@ -1937,8 +1942,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',
@@ -1952,7 +1959,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 c383c11097..e9599dea50 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.
#
--
2.39.2
next prev parent reply other threads:[~2023-04-25 6:45 UTC|newest]
Thread overview: 30+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-04-25 6:42 [PATCH v2 00/16] qapi qga/qapi-schema: Doc fixes Markus Armbruster
2023-04-25 6:42 ` [PATCH v2 01/16] qga/qapi-schema: Tidy up documentation of guest-fsfreeze-status Markus Armbruster
2023-04-25 6:42 ` [PATCH v2 02/16] qga/qapi-schema: Fix a misspelled reference Markus Armbruster
2023-04-25 6:42 ` [PATCH v2 03/16] qapi: Fix misspelled references Markus Armbruster
2023-04-25 7:17 ` Juan Quintela
2023-04-25 6:42 ` [PATCH v2 04/16] qapi: Fix up references to long gone error classes Markus Armbruster
2023-04-25 6:42 ` [PATCH v2 05/16] qapi/block-core: Clean up after removal of dirty bitmap @status Markus Armbruster
2023-04-25 6:42 ` [PATCH v2 06/16] qapi: @foo should be used to reference, not ``foo`` Markus Armbruster
2023-04-25 6:42 ` Markus Armbruster [this message]
2023-04-25 7:20 ` [PATCH v2 07/16] qapi: Tidy up examples Juan Quintela
2023-04-25 6:42 ` [PATCH v2 08/16] qapi: Delete largely misleading "Stability Considerations" Markus Armbruster
2023-04-25 6:42 ` [PATCH v2 09/16] qapi: Fix bullet list markup in documentation Markus Armbruster
2023-04-27 15:28 ` Markus Armbruster
2023-04-27 15:44 ` Juan Quintela
2023-04-25 6:42 ` [PATCH v2 10/16] qapi: Fix unintended definition lists " Markus Armbruster
2023-04-25 6:42 ` [PATCH v2 11/16] qga/qapi-schema: Fix member documentation markup Markus Armbruster
2023-04-25 6:42 ` [PATCH v2 12/16] qapi: Fix argument " Markus Armbruster
2023-04-25 6:42 ` [PATCH v2 13/16] qapi: Replace ad hoc "since" documentation by member documentation Markus Armbruster
2023-04-25 6:42 ` [PATCH v2 14/16] qapi: Fix misspelled section tags in doc comments Markus Armbruster
2023-04-25 6:42 ` [PATCH v2 15/16] qapi: Format since information the conventional way: (since X.Y) Markus Armbruster
2023-04-25 6:42 ` [PATCH v2 16/16] qapi storage-daemon/qapi: Fix documentation section structure Markus Armbruster
2023-04-27 9:53 ` [PATCH 17/16] docs/devel/qapi-code-gen: Describe some doc markup pitfalls Markus Armbruster
2023-04-27 11:09 ` Juan Quintela
2023-04-27 12:36 ` Markus Armbruster
2023-04-27 12:41 ` Vladimir Sementsov-Ogievskiy
2023-04-27 13:47 ` Vladimir Sementsov-Ogievskiy
2023-04-28 9:34 ` Markus Armbruster
2023-04-28 9:44 ` Vladimir Sementsov-Ogievskiy
2023-04-28 10:27 ` Markus Armbruster
2023-04-27 9:53 ` Markus Armbruster
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20230425064223.820979-8-armbru@redhat.com \
--to=armbru@redhat.com \
--cc=arei.gonglei@huawei.com \
--cc=david@redhat.com \
--cc=eblake@redhat.com \
--cc=eduardo@habkost.net \
--cc=hreitz@redhat.com \
--cc=jasowang@redhat.com \
--cc=jsnow@redhat.com \
--cc=kkostiuk@redhat.com \
--cc=kraxel@redhat.com \
--cc=kwolf@redhat.com \
--cc=marcandre.lureau@gmail.com \
--cc=marcandre.lureau@redhat.com \
--cc=marcel.apfelbaum@gmail.com \
--cc=michael.roth@amd.com \
--cc=pbonzini@redhat.com \
--cc=pizhenwei@bytedance.com \
--cc=qemu-block@nongnu.org \
--cc=qemu-devel@nongnu.org \
--cc=quintela@redhat.com \
--cc=stefanha@redhat.com \
--cc=vsementsov@yandex-team.ru \
--cc=wangyanan55@huawei.com \
--cc=yuval.shaia.ml@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).