rST parses something like
first line
second line
as a definition list item, where "first line" is the term being
defined by "second line".
This bites us in a couple of places. Here's one:
# @bps_max: total throughput limit during bursts,
# in bytes (Since 1.7)
scripts/qapi/parser.py parses this into an "argument section" with
name "bps_max" and text
total throughput limit during bursts,
in bytes (Since 1.7)
docs/sphinx/qapidoc.py duly passes the text to the rST parser, which
parses it as another definition list. Comes out as nested
definitions: term "bps_max: int (optional)" defined as term "total
throughput limit during bursts," defined as "in bytes (Since 1.7)".
rST truly is the Perl of ASCII-based markups.
Fix by deleting the extra indentation.
Reported-by: Peter Maydell <peter.maydell@linaro.org>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/block-core.json | 52 ++++++++++++++++++++++----------------------
qapi/control.json | 2 +-
2 files changed, 27 insertions(+), 27 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index a5a5007b28..2382772e17 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -488,41 +488,41 @@
#
# @image: the info of image used (since: 1.6)
#
-# @bps_max: total throughput limit during bursts,
-# in bytes (Since 1.7)
+# @bps_max: total throughput limit during bursts, in bytes
+# (Since 1.7)
#
-# @bps_rd_max: read throughput limit during bursts,
-# in bytes (Since 1.7)
+# @bps_rd_max: read throughput limit during bursts, in bytes
+# (Since 1.7)
#
-# @bps_wr_max: write throughput limit during bursts,
-# in bytes (Since 1.7)
+# @bps_wr_max: write throughput limit during bursts, in bytes
+# (Since 1.7)
#
-# @iops_max: total I/O operations per second during bursts,
-# in bytes (Since 1.7)
+# @iops_max: total I/O operations per second during bursts, in bytes
+# (Since 1.7)
#
-# @iops_rd_max: read I/O operations per second during bursts,
-# in bytes (Since 1.7)
+# @iops_rd_max: read I/O operations per second during bursts, in bytes
+# (Since 1.7)
#
-# @iops_wr_max: write I/O operations per second during bursts,
-# in bytes (Since 1.7)
+# @iops_wr_max: write I/O operations per second during bursts, in
+# bytes (Since 1.7)
#
-# @bps_max_length: maximum length of the @bps_max burst
-# period, in seconds. (Since 2.6)
+# @bps_max_length: maximum length of the @bps_max burst period, in
+# seconds. (Since 2.6)
#
-# @bps_rd_max_length: maximum length of the @bps_rd_max
-# burst period, in seconds. (Since 2.6)
+# @bps_rd_max_length: maximum length of the @bps_rd_max burst period,
+# in seconds. (Since 2.6)
#
-# @bps_wr_max_length: maximum length of the @bps_wr_max
-# burst period, in seconds. (Since 2.6)
+# @bps_wr_max_length: maximum length of the @bps_wr_max burst period,
+# in seconds. (Since 2.6)
#
-# @iops_max_length: maximum length of the @iops burst
-# period, in seconds. (Since 2.6)
+# @iops_max_length: maximum length of the @iops burst period, in
+# seconds. (Since 2.6)
#
-# @iops_rd_max_length: maximum length of the @iops_rd_max
-# burst period, in seconds. (Since 2.6)
+# @iops_rd_max_length: maximum length of the @iops_rd_max burst
+# period, in seconds. (Since 2.6)
#
-# @iops_wr_max_length: maximum length of the @iops_wr_max
-# burst period, in seconds. (Since 2.6)
+# @iops_wr_max_length: maximum length of the @iops_wr_max burst
+# period, in seconds. (Since 2.6)
#
# @iops_size: an I/O size in bytes (Since 1.7)
#
@@ -948,7 +948,7 @@
# by the device (Since 4.2)
#
# @invalid_rd_operations: The number of invalid read operations
-# performed by the device (Since 2.5)
+# performed by the device (Since 2.5)
#
# @invalid_wr_operations: The number of invalid write operations
# performed by the device (Since 2.5)
@@ -3735,7 +3735,7 @@
# Driver specific block device options for Quorum
#
# @blkverify: true if the driver must print content mismatch
-# set to false by default
+# set to false by default
#
# @children: the children block devices to use
#
diff --git a/qapi/control.json b/qapi/control.json
index afca2043af..f83499280a 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -195,7 +195,7 @@
# @id: Name of the monitor
#
# @mode: Selects the monitor mode (default: readline in the system
-# emulator, control in qemu-storage-daemon)
+# emulator, control in qemu-storage-daemon)
#
# @pretty: Enables pretty printing (QMP only)
#
--
2.39.2