[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 14/29] qapi/block-core.json: Use explicit bulleted lists
From: |
Peter Maydell |
Subject: |
[PATCH 14/29] qapi/block-core.json: Use explicit bulleted lists |
Date: |
Thu, 6 Feb 2020 17:30:25 +0000 |
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 <address@hidden>
---
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
- Re: [PATCH 10/29] qapi: Remove hardcoded tabs, (continued)
- [PATCH 20/29] qapi/machine.json: Escape a literal '*' in doc comment, Peter Maydell, 2020/02/06
- [PATCH 21/29] scripts/qapi: Move doc-comment whitespace stripping to doc.py, Peter Maydell, 2020/02/06
- [PATCH 14/29] qapi/block-core.json: Use explicit bulleted lists,
Peter Maydell <=
- [PATCH 16/29] qapi/{block, misc, tmp}.json: Use explicit bulleted lists, Peter Maydell, 2020/02/06
- [PATCH 19/29] qapi/qapi-schema.json: Put headers in their own doc-comment blocks, Peter Maydell, 2020/02/06
[PATCH 09/29] qapi: Fix indent level on doc comments in json files, Peter Maydell, 2020/02/06