qapi: Fix unintended definition lists in documentation

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.

Fixes: 26ec4e53f2bf (qapi: Fix indent level on doc comments in json files)
Fixes: c0ac533b6f97 (qapi: Stop using whitespace for alignment in comments)
Fixes: 81ad2964e938 (net/vmnet: add vmnet backends to qapi/net)
Reported-by: Peter Maydell <peter.maydell@linaro.org>
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>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20230425064223.820979-11-armbru@redhat.com>

diff --git a/qapi/block-core.json b/qapi/block-core.json
index a5a5007b285617a39cbe4d4c2c611117c594c2ee..2382772e1720d475d42c0d95d47ee8d2aa6550c7 100644 (file)
--- 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 afca2043af2fd5d0fc14d97786aa7f139e745a31..f83499280aa6b2f74c6028bb30d9e1720c6b5049 100644 (file)
--- 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)
 #

diff --git a/qapi/machine.json b/qapi/machine.json
index 20541cb319890ed0198e157cbc7a7b47651deb99..1a90376f4e67245b8cb87fbbfc0446225baa11f2 100644 (file)
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -457,7 +457,7 @@
 # @nodeid: NUMA node ID (increase by 1 from 0 if omitted)
 #
 # @cpus: VCPUs belonging to this node (assign VCPUS round-robin
-#         if omitted)
+#        if omitted)
 #
 # @mem: memory size of this node; mutually exclusive with @memdev.
 #       Equally divide total memory among nodes if both @mem and @memdev are
@@ -690,7 +690,7 @@
 # 5.2.27.5: Table 5-147 of ACPI 6.3 spec.
 #
 # @none: None (no memory side cache in this proximity domain,
-#              or cache associativity unknown)
+#        or cache associativity unknown)
 #
 # @direct: Direct Mapped
 #

diff --git a/qapi/net.json b/qapi/net.json
index 1f1e148f018c371f9d4ff2bf115be051db8990b6..ec66b39b70a01ccddec907d7df321e55dc736038 100644 (file)
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -533,7 +533,7 @@
 #               Must be specified along with @start-address and @subnet-mask.
 #
 # @subnet-mask: The IPv4 subnet mask to use on the interface. Must
-#                be specified along with @start-address and @subnet-mask.
+#               be specified along with @start-address and @subnet-mask.
 #
 # @isolated: Enable isolation for this interface. Interface isolation
 #            ensures that vmnet interface is not able to communicate