From: Peter Maydell <peter.maydell@linaro.org>
To: qemu-devel@nongnu.org
Cc: "Daniel P. Berrangé" <berrange@redhat.com>,
"Markus Armbruster" <armbru@redhat.com>,
"Michael Roth" <mdroth@linux.vnet.ibm.com>,
"Stefan Hajnoczi" <stefanha@redhat.com>,
"John Snow" <jsnow@redhat.com>
Subject: [PATCH 14/29] qapi/block-core.json: Use explicit bulleted lists
Date: Thu, 6 Feb 2020 17:30:25 +0000 [thread overview]
Message-ID: <20200206173040.17337-15-peter.maydell@linaro.org> (raw)
In-Reply-To: <20200206173040.17337-1-peter.maydell@linaro.org>
A JSON block comment like this:
Returns: nothing on success
If @node is not a valid block device, DeviceNotFound
If @name is not found, GenericError with an explanation
renders in the HTML and manpage like this:
Returns: nothing on success If node is not a valid block device,
DeviceNotFound If name is not found, GenericError with an explanation
because whitespace is not significant.
Use an actual bulleted list, so that the formatting is correct.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
qapi/block-core.json | 108 +++++++++++++++++++++----------------------
1 file changed, 54 insertions(+), 54 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 6cc8a4f73e0..9e878e39336 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1326,8 +1326,8 @@
#
# @size: new image size in bytes
#
-# Returns: nothing on success
-# If @device is not a valid block device, DeviceNotFound
+# Returns: - nothing on success
+# - If @device is not a valid block device, DeviceNotFound
#
# Since: 0.14.0
#
@@ -1510,8 +1510,8 @@
#
# For the arguments, see the documentation of BlockdevSnapshotSync.
#
-# Returns: nothing on success
-# If @device is not a valid block device, DeviceNotFound
+# Returns: - nothing on success
+# - If @device is not a valid block device, DeviceNotFound
#
# Since: 0.14.0
#
@@ -1586,9 +1586,8 @@
# when specifying the string or the image chain may
# not be able to be reopened again.
#
-# Returns: Nothing on success
-#
-# If "device" does not exist or cannot be determined, DeviceNotFound
+# Returns: - Nothing on success
+# - If "device" does not exist or cannot be determined, DeviceNotFound
#
# Since: 2.1
##
@@ -1674,9 +1673,9 @@
# list without user intervention.
# Defaults to true. (Since 3.1)
#
-# Returns: Nothing on success
-# If @device does not exist, DeviceNotFound
-# Any other error returns a GenericError.
+# Returns: - Nothing on success
+# - If @device does not exist, DeviceNotFound
+# - Any other error returns a GenericError.
#
# Since: 1.3
#
@@ -1704,8 +1703,8 @@
# The operation can be stopped before it has completed using the
# block-job-cancel command.
#
-# Returns: nothing on success
-# If @device is not a valid block device, GenericError
+# Returns: - nothing on success
+# - If @device is not a valid block device, GenericError
#
# Since: 1.6
#
@@ -1730,8 +1729,8 @@
# The operation can be stopped before it has completed using the
# block-job-cancel command.
#
-# Returns: nothing on success
-# If @device is not a valid block device, DeviceNotFound
+# Returns: - nothing on success
+# - If @device is not a valid block device, DeviceNotFound
#
# Since: 2.3
#
@@ -1925,8 +1924,8 @@
# format of the mirror image, default is to probe if mode='existing',
# else the format of the source.
#
-# Returns: nothing on success
-# If @device is not a valid block device, GenericError
+# Returns: - nothing on success
+# - If @device is not a valid block device, GenericError
#
# Since: 1.3
#
@@ -2097,9 +2096,9 @@
#
# Create a dirty bitmap with a name on the node, and start tracking the writes.
#
-# Returns: nothing on success
-# If @node is not a valid block device or node, DeviceNotFound
-# If @name is already taken, GenericError with an explanation
+# Returns: - nothing on success
+# - If @node is not a valid block device or node, DeviceNotFound
+# - If @name is already taken, GenericError with an explanation
#
# Since: 2.4
#
@@ -2120,10 +2119,10 @@
# with block-dirty-bitmap-add. If the bitmap is persistent, remove it from its
# storage too.
#
-# Returns: nothing on success
-# If @node is not a valid block device or node, DeviceNotFound
-# If @name is not found, GenericError with an explanation
-# if @name is frozen by an operation, GenericError
+# Returns: - nothing on success
+# - If @node is not a valid block device or node, DeviceNotFound
+# - If @name is not found, GenericError with an explanation
+# - if @name is frozen by an operation, GenericError
#
# Since: 2.4
#
@@ -2144,9 +2143,9 @@
# backup from this point in time forward will only backup clusters
# modified after this clear operation.
#
-# Returns: nothing on success
-# If @node is not a valid block device, DeviceNotFound
-# If @name is not found, GenericError with an explanation
+# Returns: - nothing on success
+# - If @node is not a valid block device, DeviceNotFound
+# - If @name is not found, GenericError with an explanation
#
# Since: 2.4
#
@@ -2165,9 +2164,9 @@
#
# Enables a dirty bitmap so that it will begin tracking disk changes.
#
-# Returns: nothing on success
-# If @node is not a valid block device, DeviceNotFound
-# If @name is not found, GenericError with an explanation
+# Returns: - nothing on success
+# - If @node is not a valid block device, DeviceNotFound
+# - If @name is not found, GenericError with an explanation
#
# Since: 4.0
#
@@ -2186,9 +2185,9 @@
#
# Disables a dirty bitmap so that it will stop tracking disk changes.
#
-# Returns: nothing on success
-# If @node is not a valid block device, DeviceNotFound
-# If @name is not found, GenericError with an explanation
+# Returns: - nothing on success
+# - If @node is not a valid block device, DeviceNotFound
+# - If @name is not found, GenericError with an explanation
#
# Since: 4.0
#
@@ -2215,11 +2214,11 @@
# of the source bitmaps. This can be used to achieve backup checkpoints, or in
# simpler usages, to copy bitmaps.
#
-# Returns: nothing on success
-# If @node is not a valid block device, DeviceNotFound
-# If any bitmap in @bitmaps or @target is not found, GenericError
-# If any of the bitmaps have different sizes or granularities,
-# GenericError
+# Returns: - nothing on success
+# - If @node is not a valid block device, DeviceNotFound
+# - If any bitmap in @bitmaps or @target is not found, GenericError
+# - If any of the bitmaps have different sizes or granularities,
+# GenericError
#
# Since: 4.0
#
@@ -2251,10 +2250,10 @@
#
# Get bitmap SHA256.
#
-# Returns: BlockDirtyBitmapSha256 on success
-# If @node is not a valid block device, DeviceNotFound
-# If @name is not found or if hashing has failed, GenericError with an
-# explanation
+# Returns: - BlockDirtyBitmapSha256 on success
+# - If @node is not a valid block device, DeviceNotFound
+# - If @name is not found or if hashing has failed, GenericError with an
+# explanation
#
# Since: 2.10
##
@@ -2371,8 +2370,8 @@
# the device will be removed from its group and the rest of its
# members will not be affected. The 'group' parameter is ignored.
#
-# Returns: Nothing on success
-# If @device is not a valid block device, DeviceNotFound
+# Returns: - Nothing on success
+# - If @device is not a valid block device, DeviceNotFound
#
# Since: 1.1
#
@@ -2622,7 +2621,8 @@
# list without user intervention.
# Defaults to true. (Since 3.1)
#
-# Returns: Nothing on success. If @device does not exist, DeviceNotFound.
+# Returns: - Nothing on success.
+# - If @device does not exist, DeviceNotFound.
#
# Since: 1.1
#
@@ -2656,8 +2656,8 @@
# @speed: the maximum speed, in bytes per second, or 0 for unlimited.
# Defaults to 0.
#
-# Returns: Nothing on success
-# If no background operation is active on this device, DeviceNotActive
+# Returns: - Nothing on success
+# - If no background operation is active on this device, DeviceNotActive
#
# Since: 1.1
##
@@ -2696,8 +2696,8 @@
# abandon the job immediately (even if it is paused) instead of waiting
# for the destination to complete its final synchronization (since 1.3)
#
-# Returns: Nothing on success
-# If no background operation is active on this device, DeviceNotActive
+# Returns: - Nothing on success
+# - If no background operation is active on this device, DeviceNotActive
#
# Since: 1.1
##
@@ -2720,8 +2720,8 @@
# the name of the parameter), but since QEMU 2.7 it can have
# other values.
#
-# Returns: Nothing on success
-# If no background operation is active on this device, DeviceNotActive
+# Returns: - Nothing on success
+# - If no background operation is active on this device, DeviceNotActive
#
# Since: 1.3
##
@@ -2742,8 +2742,8 @@
# the name of the parameter), but since QEMU 2.7 it can have
# other values.
#
-# Returns: Nothing on success
-# If no background operation is active on this device, DeviceNotActive
+# Returns: - Nothing on success
+# - If no background operation is active on this device, DeviceNotActive
#
# Since: 1.3
##
@@ -2770,8 +2770,8 @@
# the name of the parameter), but since QEMU 2.7 it can have
# other values.
#
-# Returns: Nothing on success
-# If no background operation is active on this device, DeviceNotActive
+# Returns: - Nothing on success
+# - If no background operation is active on this device, DeviceNotActive
#
# Since: 1.3
##
--
2.20.1
next prev parent reply other threads:[~2020-02-06 17:40 UTC|newest]
Thread overview: 77+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-02-06 17:30 [PATCH 00/29] Convert QAPI doc comments to generate rST instead of texinfo Peter Maydell
2020-02-06 17:30 ` [PATCH 01/29] configure: Allow user to specify sphinx-build binary Peter Maydell
2020-02-06 17:30 ` [PATCH 02/29] configure: Check that sphinx-build is using Python 3 Peter Maydell
2020-02-07 16:17 ` Markus Armbruster
2020-02-07 16:30 ` Peter Maydell
2020-02-08 7:50 ` Markus Armbruster
2020-02-08 13:11 ` Peter Maydell
2020-02-06 17:30 ` [PATCH 03/29] Makefile: Fix typo in dependency list for interop manpages Peter Maydell
2020-02-06 17:30 ` [PATCH 04/29] qga/qapi-schema.json: Fix missing '-' in GuestDiskBusType doc comment Peter Maydell
2020-02-07 8:16 ` Markus Armbruster
2020-02-06 17:30 ` [PATCH 05/29] qga/qapi-schema.json: Fix indent level on doc comments Peter Maydell
2020-02-07 8:18 ` Markus Armbruster
2020-02-07 8:22 ` Markus Armbruster
2020-02-06 17:30 ` [PATCH 06/29] qga/qapi-schema.json: minor format fixups for rST Peter Maydell
2020-02-07 8:32 ` Markus Armbruster
2020-02-13 16:20 ` Peter Maydell
2020-02-14 13:16 ` Markus Armbruster
2020-02-06 17:30 ` [PATCH 07/29] qapi/block-core.json: Use literal block for ascii art Peter Maydell
2020-02-07 8:50 ` Markus Armbruster
2020-02-07 9:27 ` Peter Maydell
2020-02-06 17:30 ` [PATCH 08/29] qapi: Use ':' after @argument in doc comments Peter Maydell
2020-02-07 9:28 ` Markus Armbruster
2020-02-07 9:33 ` Max Reitz
2020-02-07 10:24 ` Kevin Wolf
2020-02-07 11:05 ` Peter Maydell
2020-02-07 14:43 ` Markus Armbruster
2020-02-07 15:01 ` Max Reitz
2020-02-07 15:40 ` Kevin Wolf
2020-02-07 15:24 ` Peter Maydell
2020-02-08 7:54 ` Markus Armbruster
2020-02-08 13:22 ` Peter Maydell
2020-02-06 17:30 ` [PATCH 09/29] qapi: Fix indent level on doc comments in json files Peter Maydell
2020-02-07 9:31 ` Markus Armbruster
2020-02-06 17:30 ` [PATCH 10/29] qapi: Remove hardcoded tabs Peter Maydell
2020-02-07 9:32 ` Markus Armbruster
2020-02-06 17:30 ` [PATCH 11/29] qapi/ui.json: Put input-send-event body text in the right place Peter Maydell
2020-02-07 9:45 ` Markus Armbruster
2020-02-06 17:30 ` [PATCH 12/29] qapi: Explicitly put "foo: dropped in n.n" notes into Notes section Peter Maydell
2020-02-07 10:06 ` Markus Armbruster
2020-02-07 14:23 ` Eric Blake
2020-02-06 17:30 ` [PATCH 13/29] qapi/ui.json: Avoid `...' texinfo style quoting Peter Maydell
2020-02-07 10:13 ` Markus Armbruster
2020-02-06 17:30 ` Peter Maydell [this message]
2020-02-07 12:07 ` [PATCH 14/29] qapi/block-core.json: Use explicit bulleted lists Markus Armbruster
2020-02-06 17:30 ` [PATCH 15/29] qapi/ui.json: " Peter Maydell
2020-02-06 17:30 ` [PATCH 16/29] qapi/{block, misc, tmp}.json: " Peter Maydell
2020-02-07 10:33 ` Philippe Mathieu-Daudé
2020-02-06 17:30 ` [PATCH 17/29] qapi: Add blank lines before " Peter Maydell
2020-02-07 10:11 ` Philippe Mathieu-Daudé
2020-02-06 17:30 ` [PATCH 18/29] qapi/migration.json: Replace _this_ with *this* Peter Maydell
2020-02-07 16:54 ` Markus Armbruster
2020-02-07 17:00 ` Peter Maydell
2020-02-08 14:24 ` Markus Armbruster
2020-02-06 17:30 ` [PATCH 19/29] qapi/qapi-schema.json: Put headers in their own doc-comment blocks Peter Maydell
2020-02-07 15:34 ` Markus Armbruster
2020-02-07 16:13 ` Peter Maydell
2020-02-08 14:10 ` Markus Armbruster
2020-02-08 14:43 ` Peter Maydell
2020-02-06 17:30 ` [PATCH 20/29] qapi/machine.json: Escape a literal '*' in doc comment Peter Maydell
2020-02-06 17:30 ` [PATCH 21/29] scripts/qapi: Move doc-comment whitespace stripping to doc.py Peter Maydell
2020-02-06 17:30 ` [PATCH 22/29] scripts/qapi/parser.py: improve doc comment indent handling Peter Maydell
2020-02-06 17:30 ` [PATCH 23/29] docs/sphinx: Add new qapi-doc Sphinx extension Peter Maydell
2020-02-06 17:30 ` [PATCH 24/29] docs/interop: Convert qemu-ga-ref to rST Peter Maydell
2020-02-06 17:30 ` [PATCH 25/29] docs/interop: Convert qemu-qmp-ref " Peter Maydell
2020-02-06 17:30 ` [PATCH 26/29] qapi: Use rST markup for literal blocks Peter Maydell
2020-02-06 17:30 ` [PATCH 27/29] qga/qapi-schema.json: Add some headings Peter Maydell
2020-02-06 17:30 ` [PATCH 28/29] scripts/qapi: Remove texinfo generation support Peter Maydell
2020-02-06 17:59 ` Peter Maydell
2020-02-06 17:30 ` [PATCH 29/29] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions Peter Maydell
2020-02-06 18:47 ` [PATCH 00/29] Convert QAPI doc comments to generate rST instead of texinfo Peter Maydell
2020-02-06 19:53 ` no-reply
2020-02-06 19:56 ` no-reply
2020-02-07 17:00 ` Markus Armbruster
2020-02-07 17:10 ` Peter Maydell
2020-02-08 14:15 ` Markus Armbruster
2020-02-08 14:59 ` Peter Maydell
2020-02-10 0:34 ` Aleksandar Markovic
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=20200206173040.17337-15-peter.maydell@linaro.org \
--to=peter.maydell@linaro.org \
--cc=armbru@redhat.com \
--cc=berrange@redhat.com \
--cc=jsnow@redhat.com \
--cc=mdroth@linux.vnet.ibm.com \
--cc=qemu-devel@nongnu.org \
--cc=stefanha@redhat.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).