system/qemu
system/qemu
1
0
Fork 0
mirror of https://gitlab.com/qemu-project/qemu synced 2024-10-14 15:02:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

qapi: Fix unintended definition lists in documentation

Browse source 
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: 26ec4e53f2 (qapi: Fix indent level on doc comments in json files)
Fixes: c0ac533b6f (qapi: Stop using whitespace for alignment in comments)
Fixes: 81ad2964e9 (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>
This commit is contained in:
Markus Armbruster 2023-04-25 08:42:17 +02:00
parent c110102898
commit f2de3b926c
4 changed files with 30 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

52
qapi/block-core.json
View file

@ -488,41 +488,41 @@
# #
# @image: the info of image used (since: 1.6) # @image: the info of image used (since: 1.6)
# #
# @bps_max: total throughput limit during bursts, # @bps_max: total throughput limit during bursts, in bytes
# in bytes (Since 1.7) # (Since 1.7)
# #
# @bps_rd_max: read throughput limit during bursts, # @bps_rd_max: read throughput limit during bursts, in bytes
# in bytes (Since 1.7) # (Since 1.7)
# #
# @bps_wr_max: write throughput limit during bursts, # @bps_wr_max: write throughput limit during bursts, in bytes
# in bytes (Since 1.7) # (Since 1.7)
# #
# @iops_max: total I/O operations per second during bursts, # @iops_max: total I/O operations per second during bursts, in bytes
# in bytes (Since 1.7) # (Since 1.7)
# #
# @iops_rd_max: read I/O operations per second during bursts, # @iops_rd_max: read I/O operations per second during bursts, in bytes
# in bytes (Since 1.7) # (Since 1.7)
# #
# @iops_wr_max: write I/O operations per second during bursts, # @iops_wr_max: write I/O operations per second during bursts, in
# in bytes (Since 1.7) # bytes (Since 1.7)
# #
# @bps_max_length: maximum length of the @bps_max burst # @bps_max_length: maximum length of the @bps_max burst period, in
# period, in seconds. (Since 2.6) # seconds. (Since 2.6)
# #
# @bps_rd_max_length: maximum length of the @bps_rd_max # @bps_rd_max_length: maximum length of the @bps_rd_max burst period,
# burst period, in seconds. (Since 2.6) # in seconds. (Since 2.6)
# #
# @bps_wr_max_length: maximum length of the @bps_wr_max # @bps_wr_max_length: maximum length of the @bps_wr_max burst period,
# burst period, in seconds. (Since 2.6) # in seconds. (Since 2.6)
# #
# @iops_max_length: maximum length of the @iops burst # @iops_max_length: maximum length of the @iops burst period, in
# period, in seconds. (Since 2.6) # seconds. (Since 2.6)
# #
# @iops_rd_max_length: maximum length of the @iops_rd_max # @iops_rd_max_length: maximum length of the @iops_rd_max burst
# burst period, in seconds. (Since 2.6) # period, in seconds. (Since 2.6)
# #
# @iops_wr_max_length: maximum length of the @iops_wr_max # @iops_wr_max_length: maximum length of the @iops_wr_max burst
# burst period, in seconds. (Since 2.6) # period, in seconds. (Since 2.6)
# #
# @iops_size: an I/O size in bytes (Since 1.7) # @iops_size: an I/O size in bytes (Since 1.7)
# #
@ -948,7 +948,7 @@
# by the device (Since 4.2) # by the device (Since 4.2)
# #
# @invalid_rd_operations: The number of invalid read operations # @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 # @invalid_wr_operations: The number of invalid write operations
# performed by the device (Since 2.5) # performed by the device (Since 2.5)
@ -3735,7 +3735,7 @@
# Driver specific block device options for Quorum # Driver specific block device options for Quorum
# #
# @blkverify: true if the driver must print content mismatch # @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 # @children: the children block devices to use
# #

2
qapi/control.json
View file

@ -195,7 +195,7 @@
# @id: Name of the monitor # @id: Name of the monitor
# #
# @mode: Selects the monitor mode (default: readline in the system # @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) # @pretty: Enables pretty printing (QMP only)
# #

4
qapi/machine.json
View file

@ -457,7 +457,7 @@
# @nodeid: NUMA node ID (increase by 1 from 0 if omitted) # @nodeid: NUMA node ID (increase by 1 from 0 if omitted)
# #
# @cpus: VCPUs belonging to this node (assign VCPUS round-robin # @cpus: VCPUs belonging to this node (assign VCPUS round-robin
# if omitted) # if omitted)
# #
# @mem: memory size of this node; mutually exclusive with @memdev. # @mem: memory size of this node; mutually exclusive with @memdev.
# Equally divide total memory among nodes if both @mem and @memdev are # 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. # 5.2.27.5: Table 5-147 of ACPI 6.3 spec.
# #
# @none: None (no memory side cache in this proximity domain, # @none: None (no memory side cache in this proximity domain,
# or cache associativity unknown) # or cache associativity unknown)
# #
# @direct: Direct Mapped # @direct: Direct Mapped
# #

2
qapi/net.json
View file

@ -533,7 +533,7 @@
# Must be specified along with @start-address and @subnet-mask. # Must be specified along with @start-address and @subnet-mask.
# #
# @subnet-mask: The IPv4 subnet mask to use on the interface. Must # @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 # @isolated: Enable isolation for this interface. Interface isolation
# ensures that vmnet interface is not able to communicate # ensures that vmnet interface is not able to communicate