From: Markus Armbruster <armbru@redhat.com>
To: qemu-devel@nongnu.org
Cc: marcandre.lureau@redhat.com, eblake@redhat.com,
mdroth@linux.vnet.ibm.com
Subject: [Qemu-devel] [PATCH for-2.9 17/47] qapi: The #optional tag is redundant, drop
Date: Mon, 13 Mar 2017 07:18:17 +0100 [thread overview]
Message-ID: <1489385927-6735-18-git-send-email-armbru@redhat.com> (raw)
In-Reply-To: <1489385927-6735-1-git-send-email-armbru@redhat.com>
We traditionally mark optional members #optional in the doc comment.
Before commit 3313b61, this was entirely manual.
Commit 3313b61 added some automation because its qapi2texi.py relied
on #optional to determine whether a member is optional. This is no
longer the case since the previous commit: the only thing qapi2texi.py
still does with #optional is stripping it out. We still reject bogus
qapi-schema.json and six places for qga/qapi-schema.json.
Thus, you can't actually rely on #optional to see whether something is
optional. Yet we still make people add it manually. That's just
busy-work.
Drop the code to check, fix up and strip out #optional, along with all
instances of #optional. To keep it out, add code to reject it, to be
dropped again once the dust settles.
No change to generated documentation.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
docs/qapi-code-gen.txt | 16 +-
docs/writing-qmp-commands.txt | 4 +-
qapi-schema.json | 378 ++++++++++++++++----------------
qapi/block-core.json | 418 ++++++++++++++++++------------------
qapi/block.json | 8 +-
qapi/crypto.json | 22 +-
qapi/event.json | 10 +-
qapi/introspect.json | 6 +-
qapi/rocker.json | 70 +++---
qapi/trace.json | 6 +-
qga/qapi-schema.json | 38 ++--
scripts/qapi.py | 23 +-
scripts/qapi2texi.py | 3 +-
tests/Makefile.include | 1 -
tests/qapi-schema/doc-optional.err | 1 -
tests/qapi-schema/doc-optional.exit | 1 -
tests/qapi-schema/doc-optional.json | 7 -
tests/qapi-schema/doc-optional.out | 0
18 files changed, 491 insertions(+), 521 deletions(-)
delete mode 100644 tests/qapi-schema/doc-optional.err
delete mode 100644 tests/qapi-schema/doc-optional.exit
delete mode 100644 tests/qapi-schema/doc-optional.json
delete mode 100644 tests/qapi-schema/doc-optional.out
diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt
index 349dc02..4767825 100644
--- a/docs/qapi-code-gen.txt
+++ b/docs/qapi-code-gen.txt
@@ -131,10 +131,8 @@ and optional tagged sections.
FIXME: the parser accepts these things in almost any order.
-Optional arguments / members are tagged with the phrase '#optional',
-often with their default value; and extensions added after the
-expression was first released are also given a '(since x.y.z)'
-comment.
+Extensions added after the expression was first released carry a
+'(since x.y.z)' comment.
A tagged section starts with one of the following words:
"Note:"/"Notes:", "Since:", "Example"/"Examples", "Returns:", "TODO:".
@@ -150,10 +148,10 @@ For example:
#
# Statistics of a virtual block device or a block backing device.
#
-# @device: #optional If the stats are for a virtual block device, the name
-# corresponding to the virtual block device.
+# @device: If the stats are for a virtual block device, the name
+# corresponding to the virtual block device.
#
-# @node-name: #optional The node name of the device. (since 2.3)
+# @node-name: The node name of the device. (since 2.3)
#
# ... more members ...
#
@@ -168,8 +166,8 @@ For example:
#
# Query the @BlockStats for all virtual block devices.
#
-# @query-nodes: #optional If true, the command will query all the
-# block nodes ... explain, explain ... (since 2.3)
+# @query-nodes: If true, the command will query all the block nodes
+# ... explain, explain ... (since 2.3)
#
# Returns: A list of @BlockStats for each virtual block devices.
#
diff --git a/docs/writing-qmp-commands.txt b/docs/writing-qmp-commands.txt
index 44c14db..1e63754 100644
--- a/docs/writing-qmp-commands.txt
+++ b/docs/writing-qmp-commands.txt
@@ -252,7 +252,7 @@ here goes "hello-world"'s new entry for the qapi-schema.json file:
#
# Print a client provided string to the standard output stream.
#
-# @message: #optional string to be printed
+# @message: string to be printed
#
# Returns: Nothing on success.
#
@@ -358,7 +358,7 @@ The best way to return that data is to create a new QAPI type, as shown below:
#
# @clock-name: The alarm clock method's name.
#
-# @next-deadline: #optional The time (in nanoseconds) the next alarm will fire.
+# @next-deadline: The time (in nanoseconds) the next alarm will fire.
#
# Since: 1.0
##
diff --git a/qapi-schema.json b/qapi-schema.json
index 52141cd..d693033 100644
--- a/qapi-schema.json
+++ b/qapi-schema.json
@@ -150,10 +150,10 @@
#
# @fdname: file descriptor name previously passed via 'getfd' command
#
-# @skipauth: #optional whether to skip authentication. Only applies
+# @skipauth: whether to skip authentication. Only applies
# to "vnc" and "spice" protocols
#
-# @tls: #optional whether to perform TLS. Only applies to the "spice"
+# @tls: whether to perform TLS. Only applies to the "spice"
# protocol
#
# Returns: nothing on success.
@@ -176,7 +176,7 @@
#
# Guest name information.
#
-# @name: #optional The name of the guest
+# @name: The name of the guest
#
# Since: 0.14.0
##
@@ -470,7 +470,7 @@
#
# @data: data to write
#
-# @format: #optional data encoding (default 'utf8').
+# @format: data encoding (default 'utf8').
# - base64: data must be base64 encoded text. Its binary
# decoding gets written.
# - utf8: data's UTF-8 encoding is written
@@ -503,7 +503,7 @@
#
# @size: how many bytes to read at most
#
-# @format: #optional data encoding (default 'utf8').
+# @format: data encoding (default 'utf8').
# - base64: the data read is returned in base64 encoding.
# - utf8: the data read is interpreted as UTF-8.
# Bug: can screw up when the buffer contains invalid UTF-8
@@ -667,45 +667,45 @@
#
# Information about current migration process.
#
-# @status: #optional @MigrationStatus describing the current migration status.
+# @status: @MigrationStatus describing the current migration status.
# If this field is not returned, no migration process
# has been initiated
#
-# @ram: #optional @MigrationStats containing detailed migration
+# @ram: @MigrationStats containing detailed migration
# status, only returned if status is 'active' or
# 'completed'(since 1.2)
#
-# @disk: #optional @MigrationStats containing detailed disk migration
+# @disk: @MigrationStats containing detailed disk migration
# status, only returned if status is 'active' and it is a block
# migration
#
-# @xbzrle-cache: #optional @XBZRLECacheStats containing detailed XBZRLE
+# @xbzrle-cache: @XBZRLECacheStats containing detailed XBZRLE
# migration statistics, only returned if XBZRLE feature is on and
# status is 'active' or 'completed' (since 1.2)
#
-# @total-time: #optional total amount of milliseconds since migration started.
+# @total-time: total amount of milliseconds since migration started.
# If migration has ended, it returns the total migration
# time. (since 1.2)
#
-# @downtime: #optional only present when migration finishes correctly
+# @downtime: only present when migration finishes correctly
# total downtime in milliseconds for the guest.
# (since 1.3)
#
-# @expected-downtime: #optional only present while migration is active
+# @expected-downtime: only present while migration is active
# expected downtime in milliseconds for the guest in last walk
# of the dirty bitmap. (since 1.3)
#
-# @setup-time: #optional amount of setup time in milliseconds _before_ the
+# @setup-time: amount of setup time in milliseconds _before_ the
# iterations begin but _after_ the QMP command is issued. This is designed
# to provide an accounting of any activities (such as RDMA pinning) which
# may be expensive, but do not actually occur during the iterative
# migration rounds themselves. (since 1.6)
#
-# @cpu-throttle-percentage: #optional percentage of time guest cpus are being
+# @cpu-throttle-percentage: percentage of time guest cpus are being
# throttled during auto-converge. This is only present when auto-converge
# has started throttling guest cpus. (Since 2.7)
#
-# @error-desc: #optional the human readable error description string, when
+# @error-desc: the human readable error description string, when
# @status is 'failed'. Clients should not attempt to parse the
# error strings. (Since 2.7)
#
@@ -1038,21 +1038,21 @@
# ('query-migrate-parameters'), with the exception of tls-creds and
# tls-hostname.
#
-# @compress-level: #optional compression level
+# @compress-level: compression level
#
-# @compress-threads: #optional compression thread count
+# @compress-threads: compression thread count
#
-# @decompress-threads: #optional decompression thread count
+# @decompress-threads: decompression thread count
#
-# @cpu-throttle-initial: #optional Initial percentage of time guest cpus are
+# @cpu-throttle-initial: Initial percentage of time guest cpus are
# throttledwhen migration auto-converge is activated.
# The default value is 20. (Since 2.7)
#
-# @cpu-throttle-increment: #optional throttle percentage increase each time
+# @cpu-throttle-increment: throttle percentage increase each time
# auto-converge detects that migration is not making
# progress. The default value is 10. (Since 2.7)
#
-# @tls-creds: #optional ID of the 'tls-creds' object that provides credentials
+# @tls-creds: ID of the 'tls-creds' object that provides credentials
# for establishing a TLS connection over the migration data
# channel. On the outgoing side of the migration, the credentials
# must be for a 'client' endpoint, while for the incoming side the
@@ -1060,7 +1060,7 @@
# will enable TLS for all migrations. The default is unset,
# resulting in unsecured migration at the QEMU level. (Since 2.7)
#
-# @tls-hostname: #optional hostname of the target host for the migration. This
+# @tls-hostname: hostname of the target host for the migration. This
# is required when using x509 based TLS credentials and the
# migration URI does not already include a hostname. For
# example if using fd: or exec: based migration, the
@@ -1125,9 +1125,9 @@
#
# @protocol: must be "spice"
# @hostname: migration target hostname
-# @port: #optional spice tcp port for plaintext channels
-# @tls-port: #optional spice tcp port for tls-secured channels
-# @cert-subject: #optional server certificate subject
+# @port: spice tcp port for plaintext channels
+# @tls-port: spice tcp port for tls-secured channels
+# @cert-subject: server certificate subject
#
# Since: 0.14.0
#
@@ -1547,7 +1547,7 @@
#
# The network connection information for server
#
-# @auth: #optional authentication method used for
+# @auth: authentication method used for
# the plain (non-websocket) VNC server
#
# Since: 2.1
@@ -1561,10 +1561,10 @@
#
# Information about a connected VNC client.
#
-# @x509_dname: #optional If x509 authentication is in use, the Distinguished
+# @x509_dname: If x509 authentication is in use, the Distinguished
# Name of the client.
#
-# @sasl_username: #optional If SASL authentication is in use, the SASL username
+# @sasl_username: If SASL authentication is in use, the SASL username
# used for authentication.
#
# Since: 0.14.0
@@ -1580,19 +1580,19 @@
#
# @enabled: true if the VNC server is enabled, false otherwise
#
-# @host: #optional The hostname the VNC server is bound to. This depends on
+# @host: The hostname the VNC server is bound to. This depends on
# the name resolution on the host and may be an IP address.
#
-# @family: #optional 'ipv6' if the host is listening for IPv6 connections
+# @family: 'ipv6' if the host is listening for IPv6 connections
# 'ipv4' if the host is listening for IPv4 connections
# 'unix' if the host is listening on a unix domain socket
# 'unknown' otherwise
#
-# @service: #optional The service name of the server's port. This may depends
+# @service: The service name of the server's port. This may depends
# on the host system's service database so symbolic names should not
# be relied on.
#
-# @auth: #optional the current authentication type used by the server
+# @auth: the current authentication type used by the server
# 'none' if no authentication is being used
# 'vnc' if VNC authentication is being used
# 'vencrypt+plain' if VEncrypt is used with plain text authentication
@@ -1647,7 +1647,7 @@
#
# @auth: The current authentication type used by the servers
#
-# @vencrypt: #optional The vencrypt sub authentication type used by the
+# @vencrypt: The vencrypt sub authentication type used by the
# servers, only specified in case auth == vencrypt.
#
# Since: 2.9
@@ -1675,10 +1675,10 @@
#
# @auth: The current authentication type used by the non-websockets servers
#
-# @vencrypt: #optional The vencrypt authentication type used by the servers,
+# @vencrypt: The vencrypt authentication type used by the servers,
# only specified in case auth == vencrypt.
#
-# @display: #optional The display device the vnc server is linked to.
+# @display: The display device the vnc server is linked to.
#
# Since: 2.3
##
@@ -1755,7 +1755,7 @@
#
# Information about a SPICE server
#
-# @auth: #optional authentication method
+# @auth: authentication method
#
# Since: 2.1
##
@@ -1817,16 +1817,16 @@
# @migrated: true if the last guest migration completed and spice
# migration had completed as well. false otherwise. (since 1.4)
#
-# @host: #optional The hostname the SPICE server is bound to. This depends on
+# @host: The hostname the SPICE server is bound to. This depends on
# the name resolution on the host and may be an IP address.
#
-# @port: #optional The SPICE server's port number.
+# @port: The SPICE server's port number.
#
-# @compiled-version: #optional SPICE server version.
+# @compiled-version: SPICE server version.
#
-# @tls-port: #optional The SPICE server's TLS port number.
+# @tls-port: The SPICE server's TLS port number.
#
-# @auth: #optional the current authentication type used by the server
+# @auth: the current authentication type used by the server
# 'none' if no authentication is being used
# 'spice' uses SASL or direct TLS authentication, depending on command
# line options
@@ -1951,9 +1951,9 @@
#
# @size: memory size
#
-# @prefetch: #optional if @type is 'memory', true if the memory is prefetchable
+# @prefetch: if @type is 'memory', true if the memory is prefetchable
#
-# @mem_type_64: #optional if @type is 'memory', true if the BAR is 64-bit
+# @mem_type_64: if @type is 'memory', true if the BAR is 64-bit
#
# Since: 0.14.0
##
@@ -2009,7 +2009,7 @@
#
# Information about the Class of a PCI device
#
-# @desc: #optional a string description of the device's class
+# @desc: a string description of the device's class
#
# @class: the class code of the device
#
@@ -2047,7 +2047,7 @@
#
# @id: the PCI device id
#
-# @irq: #optional if an IRQ is assigned to the device, the IRQ number
+# @irq: if an IRQ is assigned to the device, the IRQ number
#
# @qdev_id: the device name of the PCI device
#
@@ -2337,7 +2337,7 @@
#
# @filename: the file to save the memory to as binary data
#
-# @cpu-index: #optional the index of the virtual CPU to use for translating the
+# @cpu-index: the index of the virtual CPU to use for translating the
# virtual address (defaults to CPU 0)
#
# Returns: Nothing on success
@@ -2566,7 +2566,7 @@
#
# Optional arguments to modify the behavior of a Transaction.
#
-# @completion-mode: #optional Controls how jobs launched asynchronously by
+# @completion-mode: Controls how jobs launched asynchronously by
# Actions will complete or fail as a group.
# See @ActionCompletionMode for details.
#
@@ -2610,7 +2610,7 @@
# @actions: List of @TransactionAction;
# information needed for the respective operations.
#
-# @properties: #optional structure of additional options to control the
+# @properties: structure of additional options to control the
# execution of the transaction. See @TransactionProperties
# for additional detail.
#
@@ -2659,7 +2659,7 @@
#
# @command-line: the command to execute in the human monitor
#
-# @cpu-index: #optional The CPU to use for commands that require an implicit CPU
+# @cpu-index: The CPU to use for commands that require an implicit CPU
#
# Returns: the output of the command as a string
#
@@ -2895,7 +2895,7 @@
#
# @password: the new password
#
-# @connected: #optional how to handle existing clients when changing the
+# @connected: how to handle existing clients when changing the
# password. If nothing is specified, defaults to `keep'
# `fail' to fail the command if clients are connected
# `disconnect' to disconnect existing clients
@@ -3054,7 +3054,7 @@
#
# @name: the name of the property
# @type: the typename of the property
-# @description: #optional if specified, the description of the property.
+# @description: if specified, the description of the property.
# (since 2.2)
#
# Since: 1.2
@@ -3084,9 +3084,9 @@
#
# @uri: the Uniform Resource Identifier of the destination VM
#
-# @blk: #optional do block migration (full disk copy)
+# @blk: do block migration (full disk copy)
#
-# @inc: #optional incremental disk copy migration
+# @inc: incremental disk copy migration
#
# @detach: this argument exists only for compatibility reasons and
# is ignored by QEMU
@@ -3195,9 +3195,9 @@
#
# @driver: the name of the new device's driver
#
-# @bus: #optional the device's parent bus (device tree path)
+# @bus: the device's parent bus (device tree path)
#
-# @id: #optional the device's ID, must be unique
+# @id: the device's ID, must be unique
#
# Additional arguments depend on the type.
#
@@ -3310,17 +3310,17 @@
# 2. fd: the protocol starts with "fd:", and the following string
# is the fd's name.
#
-# @detach: #optional if true, QMP will return immediately rather than
+# @detach: if true, QMP will return immediately rather than
# waiting for the dump to finish. The user can track progress
# using "query-dump". (since 2.6).
#
-# @begin: #optional if specified, the starting physical address.
+# @begin: if specified, the starting physical address.
#
-# @length: #optional if specified, the memory size, in bytes. If you don't
+# @length: if specified, the memory size, in bytes. If you don't
# want to dump all guest's memory, please specify the start @begin
# and @length
#
-# @format: #optional if specified, the format of guest memory dump. But non-elf
+# @format: if specified, the format of guest memory dump. But non-elf
# format is conflict with paging and filter, ie. @paging, @begin and
# @length is not allowed to be specified with non-elf @format at the
# same time (since 2.0)
@@ -3512,7 +3512,7 @@
#
# @id: the name of the new object
#
-# @props: #optional a dictionary of properties to be passed to the backend
+# @props: a dictionary of properties to be passed to the backend
#
# Returns: Nothing on success
# Error if @qom-type is not a valid class name
@@ -3565,15 +3565,15 @@
#
# Create a new Network Interface Card.
#
-# @netdev: #optional id of -netdev to connect to
+# @netdev: id of -netdev to connect to
#
-# @macaddr: #optional MAC address
+# @macaddr: MAC address
#
-# @model: #optional device model (e1000, rtl8139, virtio etc.)
+# @model: device model (e1000, rtl8139, virtio etc.)
#
-# @addr: #optional PCI device address
+# @addr: PCI device address
#
-# @vectors: #optional number of MSI-x vectors, 0 to disable MSI-X
+# @vectors: number of MSI-x vectors, 0 to disable MSI-X
#
# Since: 1.2
##
@@ -3602,57 +3602,57 @@
# Use the user mode network stack which requires no administrator privilege to
# run.
#
-# @hostname: #optional client hostname reported by the builtin DHCP server
+# @hostname: client hostname reported by the builtin DHCP server
#
-# @restrict: #optional isolate the guest from the host
+# @restrict: isolate the guest from the host
#
-# @ipv4: #optional whether to support IPv4, default true for enabled
+# @ipv4: whether to support IPv4, default true for enabled
# (since 2.6)
#
-# @ipv6: #optional whether to support IPv6, default true for enabled
+# @ipv6: whether to support IPv6, default true for enabled
# (since 2.6)
#
-# @ip: #optional legacy parameter, use net= instead
+# @ip: legacy parameter, use net= instead
#
-# @net: #optional IP network address that the guest will see, in the
+# @net: IP network address that the guest will see, in the
# form addr[/netmask] The netmask is optional, and can be
# either in the form a.b.c.d or as a number of valid top-most
# bits. Default is 10.0.2.0/24.
#
-# @host: #optional guest-visible address of the host
+# @host: guest-visible address of the host
#
-# @tftp: #optional root directory of the built-in TFTP server
+# @tftp: root directory of the built-in TFTP server
#
-# @bootfile: #optional BOOTP filename, for use with tftp=
+# @bootfile: BOOTP filename, for use with tftp=
#
-# @dhcpstart: #optional the first of the 16 IPs the built-in DHCP server can
+# @dhcpstart: the first of the 16 IPs the built-in DHCP server can
# assign
#
-# @dns: #optional guest-visible address of the virtual nameserver
+# @dns: guest-visible address of the virtual nameserver
#
-# @dnssearch: #optional list of DNS suffixes to search, passed as DHCP option
+# @dnssearch: list of DNS suffixes to search, passed as DHCP option
# to the guest
#
-# @ipv6-prefix: #optional IPv6 network prefix (default is fec0::) (since
+# @ipv6-prefix: IPv6 network prefix (default is fec0::) (since
# 2.6). The network prefix is given in the usual
# hexadecimal IPv6 address notation.
#
-# @ipv6-prefixlen: #optional IPv6 network prefix length (default is 64)
+# @ipv6-prefixlen: IPv6 network prefix length (default is 64)
# (since 2.6)
#
-# @ipv6-host: #optional guest-visible IPv6 address of the host (since 2.6)
+# @ipv6-host: guest-visible IPv6 address of the host (since 2.6)
#
-# @ipv6-dns: #optional guest-visible IPv6 address of the virtual
+# @ipv6-dns: guest-visible IPv6 address of the virtual
# nameserver (since 2.6)
#
-# @smb: #optional root directory of the built-in SMB server
+# @smb: root directory of the built-in SMB server
#
-# @smbserver: #optional IP address of the built-in SMB server
+# @smbserver: IP address of the built-in SMB server
#
-# @hostfwd: #optional redirect incoming TCP or UDP host connections to guest
+# @hostfwd: redirect incoming TCP or UDP host connections to guest
# endpoints
#
-# @guestfwd: #optional forward guest TCP connections
+# @guestfwd: forward guest TCP connections
#
# Since: 1.2
##
@@ -3684,37 +3684,37 @@
#
# Connect the host TAP network interface name to the VLAN.
#
-# @ifname: #optional interface name
+# @ifname: interface name
#
-# @fd: #optional file descriptor of an already opened tap
+# @fd: file descriptor of an already opened tap
#
-# @fds: #optional multiple file descriptors of already opened multiqueue capable
+# @fds: multiple file descriptors of already opened multiqueue capable
# tap
#
-# @script: #optional script to initialize the interface
+# @script: script to initialize the interface
#
-# @downscript: #optional script to shut down the interface
+# @downscript: script to shut down the interface
#
-# @br: #optional bridge name (since 2.8)
+# @br: bridge name (since 2.8)
#
-# @helper: #optional command to execute to configure bridge
+# @helper: command to execute to configure bridge
#
-# @sndbuf: #optional send buffer limit. Understands [TGMKkb] suffixes.
+# @sndbuf: send buffer limit. Understands [TGMKkb] suffixes.
#
-# @vnet_hdr: #optional enable the IFF_VNET_HDR flag on the tap interface
+# @vnet_hdr: enable the IFF_VNET_HDR flag on the tap interface
#
-# @vhost: #optional enable vhost-net network accelerator
+# @vhost: enable vhost-net network accelerator
#
-# @vhostfd: #optional file descriptor of an already opened vhost net device
+# @vhostfd: file descriptor of an already opened vhost net device
#
-# @vhostfds: #optional file descriptors of multiple already opened vhost net
+# @vhostfds: file descriptors of multiple already opened vhost net
# devices
#
-# @vhostforce: #optional vhost on for non-MSIX virtio guests
+# @vhostforce: vhost on for non-MSIX virtio guests
#
-# @queues: #optional number of queues to be created for multiqueue capable tap
+# @queues: number of queues to be created for multiqueue capable tap
#
-# @poll-us: #optional maximum number of microseconds that could
+# @poll-us: maximum number of microseconds that could
# be spent on busy polling for tap (since 2.7)
#
# Since: 1.2
@@ -3743,17 +3743,17 @@
# Connect the VLAN to a remote VLAN in another QEMU virtual machine using a TCP
# socket connection.
#
-# @fd: #optional file descriptor of an already opened socket
+# @fd: file descriptor of an already opened socket
#
-# @listen: #optional port number, and optional hostname, to listen on
+# @listen: port number, and optional hostname, to listen on
#
-# @connect: #optional port number, and optional hostname, to connect to
+# @connect: port number, and optional hostname, to connect to
#
-# @mcast: #optional UDP multicast address and port number
+# @mcast: UDP multicast address and port number
#
-# @localaddr: #optional source address and port for multicast and udp packets
+# @localaddr: source address and port for multicast and udp packets
#
-# @udp: #optional UDP unicast address and port number
+# @udp: UDP unicast address and port number
#
# Since: 1.2
##
@@ -3775,32 +3775,32 @@
#
# @dst: destination address
#
-# @srcport: #optional source port - mandatory for udp, optional for ip
+# @srcport: source port - mandatory for udp, optional for ip
#
-# @dstport: #optional destination port - mandatory for udp, optional for ip
+# @dstport: destination port - mandatory for udp, optional for ip
#
-# @ipv6: #optional force the use of ipv6
+# @ipv6: force the use of ipv6
#
-# @udp: #optional use the udp version of l2tpv3 encapsulation
+# @udp: use the udp version of l2tpv3 encapsulation
#
-# @cookie64: #optional use 64 bit coookies
+# @cookie64: use 64 bit coookies
#
-# @counter: #optional have sequence counter
+# @counter: have sequence counter
#
-# @pincounter: #optional pin sequence counter to zero -
+# @pincounter: pin sequence counter to zero -
# workaround for buggy implementations or
# networks with packet reorder
#
-# @txcookie: #optional 32 or 64 bit transmit cookie
+# @txcookie: 32 or 64 bit transmit cookie
#
-# @rxcookie: #optional 32 or 64 bit receive cookie
+# @rxcookie: 32 or 64 bit receive cookie
#
# @txsession: 32 bit transmit session
#
-# @rxsession: #optional 32 bit receive session - if not specified
+# @rxsession: 32 bit receive session - if not specified
# set to the same value as transmit
#
-# @offset: #optional additional offset - allows the insertion of
+# @offset: additional offset - allows the insertion of
# additional application-specific data before the packet payload
#
# Since: 2.1
@@ -3827,13 +3827,13 @@
#
# Connect the VLAN to a vde switch running on the host.
#
-# @sock: #optional socket path
+# @sock: socket path
#
-# @port: #optional port number
+# @port: port number
#
-# @group: #optional group owner of socket
+# @group: group owner of socket
#
-# @mode: #optional permissions for socket
+# @mode: permissions for socket
#
# Since: 1.2
##
@@ -3849,10 +3849,10 @@
#
# Dump VLAN network traffic to a file.
#
-# @len: #optional per-packet size limit (64k default). Understands [TGMKkb]
+# @len: per-packet size limit (64k default). Understands [TGMKkb]
# suffixes.
#
-# @file: #optional dump file path (default is qemu-vlan0.pcap)
+# @file: dump file path (default is qemu-vlan0.pcap)
#
# Since: 1.2
##
@@ -3866,9 +3866,9 @@
#
# Connect a host TAP network interface to a host bridge device.
#
-# @br: #optional bridge name
+# @br: bridge name
#
-# @helper: #optional command to execute to configure bridge
+# @helper: command to execute to configure bridge
#
# Since: 1.2
##
@@ -3902,7 +3902,7 @@
# YYY identifies a port of the switch. VALE ports having the
# same XXX are therefore connected to the same switch.
#
-# @devname: #optional path of the netmap device (default: '/dev/netmap').
+# @devname: path of the netmap device (default: '/dev/netmap').
#
# Since: 2.0
##
@@ -3918,9 +3918,9 @@
#
# @chardev: name of a unix socket chardev
#
-# @vhostforce: #optional vhost on for non-MSIX virtio guests (default: false).
+# @vhostforce: vhost on for non-MSIX virtio guests (default: false).
#
-# @queues: #optional number of queues to be created for multiqueue vhost-user
+# @queues: number of queues to be created for multiqueue vhost-user
# (default: 1) (Since 2.5)
#
# Since: 2.1
@@ -3977,11 +3977,11 @@
#
# Captures the configuration of a network device; legacy.
#
-# @vlan: #optional vlan number
+# @vlan: vlan number
#
-# @id: #optional identifier for monitor commands
+# @id: identifier for monitor commands
#
-# @name: #optional identifier for monitor commands, ignored if @id is present
+# @name: identifier for monitor commands, ignored if @id is present
#
# @opts: device type specific properties (legacy)
#
@@ -4055,17 +4055,15 @@
#
# @port: port part of the address, or lowest port if @to is present
#
-# @numeric: #optional true if the host/port are guaranteed to be numeric,
+# @numeric: true if the host/port are guaranteed to be numeric,
# false if name resolution should be attempted. Defaults to false.
# (Since 2.9)
#
# @to: highest port to try
#
# @ipv4: whether to accept IPv4 addresses, default try both IPv4 and IPv6
-# #optional
#
# @ipv6: whether to accept IPv6 addresses, default try both IPv4 and IPv6
-# #optional
#
# Since: 1.3
##
@@ -4213,9 +4211,9 @@
#
# @name: the name of the machine
#
-# @alias: #optional an alias for the machine name
+# @alias: an alias for the machine name
#
-# @is-default: #optional whether the machine is default
+# @is-default: whether the machine is default
#
# @cpu-max: maximum number of CPUs supported by the machine type
# (since 1.5.0)
@@ -4247,7 +4245,7 @@
#
# @name: the name of the CPU definition
#
-# @migration-safe: #optional whether a CPU definition can be safely used for
+# @migration-safe: whether a CPU definition can be safely used for
# migration in combination with a QEMU compatibility machine
# when migrating between different QMU versions and between
# hosts with different sets of (hardware or software)
@@ -4259,7 +4257,7 @@
# QEMU version, machine type, machine options and accelerator options.
# A static model is always migration-safe. (since 2.8)
#
-# @unavailable-features: #optional List of properties that prevent
+# @unavailable-features: List of properties that prevent
# the CPU model from running in the current
# host. (since 2.8)
# @typename: Type name that can be used as argument to @device-list-properties,
@@ -4310,7 +4308,7 @@
# However, if required, architectures can expose relevant properties.
#
# @name: the name of the CPU definition the model is based on
-# @props: #optional a dictionary of QOM properties to be applied
+# @props: a dictionary of QOM properties to be applied
#
# Since: 2.8.0
##
@@ -4559,9 +4557,9 @@
#
# Add a file descriptor, that was passed via SCM rights, to an fd set.
#
-# @fdset-id: #optional The ID of the fd set to add the file descriptor to.
+# @fdset-id: The ID of the fd set to add the file descriptor to.
#
-# @opaque: #optional A free-form string that can be used to describe the fd.
+# @opaque: A free-form string that can be used to describe the fd.
#
# Returns: @AddfdInfo on success
#
@@ -4591,7 +4589,7 @@
#
# @fdset-id: The ID of the fd set that the file descriptor belongs to.
#
-# @fd: #optional The file descriptor that is to be removed.
+# @fd: The file descriptor that is to be removed.
#
# Returns: Nothing on success
# If @fdset-id or @fd is not found, FdNotFound
@@ -4618,7 +4616,7 @@
#
# @fd: The file descriptor value.
#
-# @opaque: #optional A free-form string that can be used to describe the fd.
+# @opaque: A free-form string that can be used to describe the fd.
#
# Since: 1.2.0
##
@@ -4769,7 +4767,7 @@
# directly to the guest, while @KeyValue.qcode must be a valid
# @QKeyCode value
#
-# @hold-time: #optional time to delay key up events, milliseconds. Defaults
+# @hold-time: time to delay key up events, milliseconds. Defaults
# to 100
#
# Returns: Nothing on success
@@ -4815,8 +4813,8 @@
#
# Configuration shared across all chardev backends
#
-# @logfile: #optional The name of a logfile to save output
-# @logappend: #optional true to append instead of truncate
+# @logfile: The name of a logfile to save output
+# @logappend: true to append instead of truncate
# (default to false to truncate)
#
# Since: 2.6
@@ -4829,9 +4827,9 @@
#
# Configuration info for file chardevs.
#
-# @in: #optional The name of the input file
+# @in: The name of the input file
# @out: The name of the output file
-# @append: #optional Open the file in append mode (default false to
+# @append: Open the file in append mode (default false to
# truncate) (Since 2.6)
#
# Since: 1.4
@@ -4861,14 +4859,14 @@
#
# @addr: socket address to listen on (server=true)
# or connect to (server=false)
-# @tls-creds: #optional the ID of the TLS credentials object (since 2.6)
-# @server: #optional create server socket (default: true)
-# @wait: #optional wait for incoming connection on server
+# @tls-creds: the ID of the TLS credentials object (since 2.6)
+# @server: create server socket (default: true)
+# @wait: wait for incoming connection on server
# sockets (default: false).
-# @nodelay: #optional set TCP_NODELAY socket option (default: false)
-# @telnet: #optional enable telnet protocol on server
+# @nodelay: set TCP_NODELAY socket option (default: false)
+# @telnet: enable telnet protocol on server
# sockets (default: false)
-# @reconnect: #optional For a client socket, if a socket is disconnected,
+# @reconnect: For a client socket, if a socket is disconnected,
# then attempt a reconnect after the given number of seconds.
# Setting this to zero disables this function. (default: 0)
# (Since: 2.2)
@@ -4890,7 +4888,7 @@
# Configuration info for datagram socket chardevs.
#
# @remote: remote address
-# @local: #optional local address
+# @local: local address
#
# Since: 1.5
##
@@ -4915,7 +4913,7 @@
#
# Configuration info for stdio chardevs.
#
-# @signal: #optional Allow signals (such as SIGINT triggered by ^C)
+# @signal: Allow signals (such as SIGINT triggered by ^C)
# be delivered to qemu. Default: true in -nographic mode,
# false otherwise.
#
@@ -4972,7 +4970,7 @@
#
# Configuration info for ring buffer chardevs.
#
-# @size: #optional ring buffer size, must be power of two, default is 65536
+# @size: ring buffer size, must be power of two, default is 65536
#
# Since: 1.5
##
@@ -5013,7 +5011,7 @@
#
# Return info about the chardev backend just created.
#
-# @pty: #optional name of the slave pseudoterminal device, present if
+# @pty: name of the slave pseudoterminal device, present if
# and only if a chardev of type 'pty' was created
#
# Since: 1.4
@@ -5135,9 +5133,9 @@
#
# Information about the TPM passthrough type
#
-# @path: #optional string describing the path used for accessing the TPM device
+# @path: string describing the path used for accessing the TPM device
#
-# @cancel-path: #optional string showing the TPM's sysfs cancel file
+# @cancel-path: string showing the TPM's sysfs cancel file
# for cancellation of TPM commands while they are executing
#
# Since: 1.5
@@ -5223,28 +5221,28 @@
# String fields are copied into the matching ACPI member from lowest address
# upwards, and silently truncated / NUL-padded to length.
#
-# @sig: #optional table signature / identifier (4 bytes)
+# @sig: table signature / identifier (4 bytes)
#
-# @rev: #optional table revision number (dependent on signature, 1 byte)
+# @rev: table revision number (dependent on signature, 1 byte)
#
-# @oem_id: #optional OEM identifier (6 bytes)
+# @oem_id: OEM identifier (6 bytes)
#
-# @oem_table_id: #optional OEM table identifier (8 bytes)
+# @oem_table_id: OEM table identifier (8 bytes)
#
-# @oem_rev: #optional OEM-supplied revision number (4 bytes)
+# @oem_rev: OEM-supplied revision number (4 bytes)
#
-# @asl_compiler_id: #optional identifier of the utility that created the table
+# @asl_compiler_id: identifier of the utility that created the table
# (4 bytes)
#
-# @asl_compiler_rev: #optional revision number of the utility that created the
+# @asl_compiler_rev: revision number of the utility that created the
# table (4 bytes)
#
-# @file: #optional colon (:) separated list of pathnames to load and
+# @file: colon (:) separated list of pathnames to load and
# concatenate as table data. The resultant binary blob is expected to
# have an ACPI table header. At least one file is required. This field
# excludes @data.
#
-# @data: #optional colon (:) separated list of pathnames to load and
+# @data: colon (:) separated list of pathnames to load and
# concatenate as table data. The resultant binary blob must not have an
# ACPI table header. At least one file is required. This field excludes
# @file.
@@ -5291,9 +5289,9 @@
#
# @type: parameter @CommandLineParameterType
#
-# @help: #optional human readable text string, not suitable for parsing.
+# @help: human readable text string, not suitable for parsing.
#
-# @default: #optional default value string (since 2.1)
+# @default: default value string (since 2.1)
#
# Since: 1.5
##
@@ -5322,7 +5320,7 @@
#
# Query command line option schema.
#
-# @option: #optional option name
+# @option: option name
#
# Returns: list of @CommandLineOptionInfo for all options (or for the given
# @option). Returns an error if the given @option doesn't exist.
@@ -5371,7 +5369,7 @@
#
# @cpuid-input-eax: Input EAX value for CPUID instruction for that feature word
#
-# @cpuid-input-ecx: #optional Input ECX value for CPUID instruction for that
+# @cpuid-input-ecx: Input ECX value for CPUID instruction for that
# feature word
#
# @cpuid-register: Output register containing the feature bits
@@ -5463,7 +5461,7 @@
#
# Return rx-filter information for all NICs (or for the given NIC).
#
-# @name: #optional net client name
+# @name: net client name
#
# Returns: list of @RxFilterInfo for all NICs (or for the given NIC).
# Returns an error if the given @name doesn't exist, or given
@@ -5597,8 +5595,8 @@
#
# Send input event(s) to guest.
#
-# @device: #optional display device to send event(s) to.
-# @head: #optional head to send event(s) to, in case the
+# @device: display device to send event(s) to.
+# @head: head to send event(s) to, in case the
# display device supports multiple scanouts.
# @events: List of InputEvent union.
#
@@ -5690,16 +5688,16 @@
#
# Create a guest NUMA node. (for OptsVisitor)
#
-# @nodeid: #optional NUMA node ID (increase by 1 from 0 if omitted)
+# @nodeid: NUMA node ID (increase by 1 from 0 if omitted)
#
-# @cpus: #optional VCPUs belonging to this node (assign VCPUS round-robin
+# @cpus: VCPUs belonging to this node (assign VCPUS round-robin
# if omitted)
#
-# @mem: #optional 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
# omitted.
#
-# @memdev: #optional memory backend object. If specified for one node,
+# @memdev: memory backend object. If specified for one node,
# it must be specified for all nodes.
#
# Since: 2.1
@@ -5736,7 +5734,7 @@
#
# Information about memory backend
#
-# @id: #optional backend's ID if backend has 'id' property (since 2.9)
+# @id: backend's ID if backend has 'id' property (since 2.9)
#
# @size: memory backend size
#
@@ -5803,7 +5801,7 @@
#
# PCDIMMDevice state information
#
-# @id: #optional device's ID
+# @id: device's ID
#
# @addr: physical address, where device is mapped
#
@@ -5882,7 +5880,7 @@
# For description of possible values of @source and @status fields
# see "_OST (OSPM Status Indication)" chapter of ACPI5.0 spec.
#
-# @device: #optional device ID associated with slot
+# @device: device ID associated with slot
#
# @slot: slot ID, unique per slot of a given @slot-type
#
@@ -6080,7 +6078,7 @@
#
# @primary: true for primary or false for secondary.
#
-# @failover: #optional true to do failover, false to stop. but cannot be
+# @failover: true to do failover, false to stop. but cannot be
# specified if 'enable' is true. default value is false.
#
# Returns: nothing.
@@ -6103,7 +6101,7 @@
#
# @error: true if an error happened, false if replication is normal.
#
-# @desc: #optional the human readable error description string, when
+# @desc: the human readable error description string, when
# @error is 'true'.
#
# Since: 2.9
@@ -6194,10 +6192,10 @@
# it should be passed by management with device_add command when
# a CPU is being hotplugged.
#
-# @node-id: #optional NUMA node ID the CPU belongs to
-# @socket-id: #optional socket number within node/board the CPU belongs to
-# @core-id: #optional core number within socket the CPU belongs to
-# @thread-id: #optional thread number within core the CPU belongs to
+# @node-id: NUMA node ID the CPU belongs to
+# @socket-id: socket number within node/board the CPU belongs to
+# @core-id: core number within socket the CPU belongs to
+# @thread-id: thread number within core the CPU belongs to
#
# Note: currently there are 4 properties that could be present
# but management should be prepared to pass through other
@@ -6221,7 +6219,7 @@
# @type: CPU object type for usage with device_add command
# @props: list of properties to be used for hotplugging CPU
# @vcpus-count: number of logical VCPU threads @HotpluggableCPU provides
-# @qom-path: #optional link to existing CPU object if CPU is present or
+# @qom-path: link to existing CPU object if CPU is present or
# omitted if CPU is not present.
#
# Since: 2.7
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 9bb7f4a..539649c 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -37,9 +37,9 @@
#
# @compat: compatibility level
#
-# @lazy-refcounts: #optional on or off; only valid for compat >= 1.1
+# @lazy-refcounts: on or off; only valid for compat >= 1.1
#
-# @corrupt: #optional true if the image has been marked corrupt; only valid for
+# @corrupt: true if the image has been marked corrupt; only valid for
# compat >= 1.1 (since 2.2)
#
# @refcount-bits: width of a refcount entry in bits (since 2.3)
@@ -103,27 +103,27 @@
#
# @virtual-size: maximum capacity in bytes of the image
#
-# @actual-size: #optional actual size on disk in bytes of the image
+# @actual-size: actual size on disk in bytes of the image
#
-# @dirty-flag: #optional true if image is not cleanly closed
+# @dirty-flag: true if image is not cleanly closed
#
-# @cluster-size: #optional size of a cluster in bytes
+# @cluster-size: size of a cluster in bytes
#
-# @encrypted: #optional true if the image is encrypted
+# @encrypted: true if the image is encrypted
#
-# @compressed: #optional true if the image is compressed (Since 1.7)
+# @compressed: true if the image is compressed (Since 1.7)
#
-# @backing-filename: #optional name of the backing file
+# @backing-filename: name of the backing file
#
-# @full-backing-filename: #optional full path of the backing file
+# @full-backing-filename: full path of the backing file
#
-# @backing-filename-format: #optional the format of the backing file
+# @backing-filename-format: the format of the backing file
#
-# @snapshots: #optional list of VM snapshots
+# @snapshots: list of VM snapshots
#
-# @backing-image: #optional info of the backing image (since 1.6)
+# @backing-image: info of the backing image (since 1.6)
#
-# @format-specific: #optional structure supplying additional format-specific
+# @format-specific: structure supplying additional format-specific
# information (since 1.7)
#
# Since: 1.3
@@ -149,31 +149,31 @@
#
# @check-errors: number of unexpected errors occurred during check
#
-# @image-end-offset: #optional offset (in bytes) where the image ends, this
+# @image-end-offset: offset (in bytes) where the image ends, this
# field is present if the driver for the image format
# supports it
#
-# @corruptions: #optional number of corruptions found during the check if any
+# @corruptions: number of corruptions found during the check if any
#
-# @leaks: #optional number of leaks found during the check if any
+# @leaks: number of leaks found during the check if any
#
-# @corruptions-fixed: #optional number of corruptions fixed during the check
+# @corruptions-fixed: number of corruptions fixed during the check
# if any
#
-# @leaks-fixed: #optional number of leaks fixed during the check if any
+# @leaks-fixed: number of leaks fixed during the check if any
#
-# @total-clusters: #optional total number of clusters, this field is present
+# @total-clusters: total number of clusters, this field is present
# if the driver for the image format supports it
#
-# @allocated-clusters: #optional total number of allocated clusters, this
+# @allocated-clusters: total number of allocated clusters, this
# field is present if the driver for the image format
# supports it
#
-# @fragmented-clusters: #optional total number of fragmented clusters, this
+# @fragmented-clusters: total number of fragmented clusters, this
# field is present if the driver for the image format
# supports it
#
-# @compressed-clusters: #optional total number of compressed clusters, this
+# @compressed-clusters: total number of compressed clusters, this
# field is present if the driver for the image format
# supports it
#
@@ -202,9 +202,9 @@
#
# @depth: the depth of the mapping
#
-# @offset: #optional the offset in file that the virtual sectors are mapped to
+# @offset: the offset in file that the virtual sectors are mapped to
#
-# @filename: #optional filename that is referred to by @offset
+# @filename: filename that is referred to by @offset
#
# Since: 2.6
#
@@ -237,7 +237,7 @@
#
# @file: the filename of the backing device
#
-# @node-name: #optional the name of the block driver node (Since 2.0)
+# @node-name: the name of the block driver node (Since 2.0)
#
# @ro: true if the backing device was open read-only
#
@@ -252,7 +252,7 @@
# 2.6: 'luks' added
# 2.8: 'replication' added, 'tftp' dropped
#
-# @backing_file: #optional the name of the backing file (for copy-on-write)
+# @backing_file: the name of the backing file (for copy-on-write)
#
# @backing_file_depth: number of files in the backing file chain (since: 1.2)
#
@@ -277,45 +277,45 @@
#
# @image: the info of image used (since: 1.6)
#
-# @bps_max: #optional total throughput limit during bursts,
+# @bps_max: total throughput limit during bursts,
# in bytes (Since 1.7)
#
-# @bps_rd_max: #optional read throughput limit during bursts,
+# @bps_rd_max: read throughput limit during bursts,
# in bytes (Since 1.7)
#
-# @bps_wr_max: #optional write throughput limit during bursts,
+# @bps_wr_max: write throughput limit during bursts,
# in bytes (Since 1.7)
#
-# @iops_max: #optional total I/O operations per second during bursts,
+# @iops_max: total I/O operations per second during bursts,
# in bytes (Since 1.7)
#
-# @iops_rd_max: #optional read I/O operations per second during bursts,
+# @iops_rd_max: read I/O operations per second during bursts,
# in bytes (Since 1.7)
#
-# @iops_wr_max: #optional write I/O operations per second during bursts,
+# @iops_wr_max: write I/O operations per second during bursts,
# in bytes (Since 1.7)
#
-# @bps_max_length: #optional maximum length of the @bps_max burst
+# @bps_max_length: maximum length of the @bps_max burst
# period, in seconds. (Since 2.6)
#
-# @bps_rd_max_length: #optional maximum length of the @bps_rd_max
+# @bps_rd_max_length: maximum length of the @bps_rd_max
# burst period, in seconds. (Since 2.6)
#
-# @bps_wr_max_length: #optional maximum length of the @bps_wr_max
+# @bps_wr_max_length: maximum length of the @bps_wr_max
# burst period, in seconds. (Since 2.6)
#
-# @iops_max_length: #optional maximum length of the @iops burst
+# @iops_max_length: maximum length of the @iops burst
# period, in seconds. (Since 2.6)
#
-# @iops_rd_max_length: #optional maximum length of the @iops_rd_max
+# @iops_rd_max_length: maximum length of the @iops_rd_max
# burst period, in seconds. (Since 2.6)
#
-# @iops_wr_max_length: #optional maximum length of the @iops_wr_max
+# @iops_wr_max_length: maximum length of the @iops_wr_max
# burst period, in seconds. (Since 2.6)
#
-# @iops_size: #optional an I/O size in bytes (Since 1.7)
+# @iops_size: an I/O size in bytes (Since 1.7)
#
-# @group: #optional throttle group name (Since 2.4)
+# @group: throttle group name (Since 2.4)
#
# @cache: the cache mode used for the block device (since: 2.3)
#
@@ -410,7 +410,7 @@
#
# Block dirty bitmap information.
#
-# @name: #optional the name of the dirty bitmap (Since 2.4)
+# @name: the name of the dirty bitmap (Since 2.4)
#
# @count: number of dirty bytes according to the dirty bitmap
#
@@ -440,17 +440,17 @@
# @locked: True if the guest has locked this device from having its media
# removed
#
-# @tray_open: #optional True if the device's tray is open
+# @tray_open: True if the device's tray is open
# (only present if it has a tray)
#
-# @dirty-bitmaps: #optional dirty bitmaps information (only present if the
+# @dirty-bitmaps: dirty bitmaps information (only present if the
# driver has one or more dirty bitmaps) (Since 2.0)
#
-# @io-status: #optional @BlockDeviceIoStatus. Only present if the device
+# @io-status: @BlockDeviceIoStatus. Only present if the device
# supports it and the VM is configured to stop on errors
# (supported device models: virtio-blk, ide, scsi-disk)
#
-# @inserted: #optional @BlockDeviceInfo describing the device if media is
+# @inserted: @BlockDeviceInfo describing the device if media is
# present
#
# Since: 0.14.0
@@ -639,7 +639,7 @@
# @wr_merged: Number of write requests that have been merged into another
# request (Since 2.3).
#
-# @idle_time_ns: #optional Time since the last I/O operation, in
+# @idle_time_ns: Time since the last I/O operation, in
# nanoseconds. If the field is absent it means that
# there haven't been any operations yet (Since 2.5).
#
@@ -689,19 +689,19 @@
#
# Statistics of a virtual block device or a block backing device.
#
-# @device: #optional If the stats are for a virtual block device, the name
+# @device: If the stats are for a virtual block device, the name
# corresponding to the virtual block device.
#
-# @node-name: #optional The node name of the device. (Since 2.3)
+# @node-name: The node name of the device. (Since 2.3)
#
# @stats: A @BlockDeviceStats for the device.
#
-# @parent: #optional This describes the file block device if it has one.
+# @parent: This describes the file block device if it has one.
# Contains recursively the statistics of the underlying
# protocol (e.g. the host file for a qcow2 image). If there is
# no underlying protocol, this field is omitted
#
-# @backing: #optional This describes the backing block device if it has one.
+# @backing: This describes the backing block device if it has one.
# (Since 2.0)
#
# Since: 0.14.0
@@ -717,7 +717,7 @@
#
# Query the @BlockStats for all virtual block devices.
#
-# @query-nodes: #optional If true, the command will query all the block nodes
+# @query-nodes: If true, the command will query all the block nodes
# that have a node name, in a list which will include "parent"
# information, but not "backing".
# If false or omitted, the behavior is as before - query all the
@@ -956,9 +956,9 @@
#
# Either @device or @node-name must be set but not both.
#
-# @device: #optional the name of the block backend device to set the password on
+# @device: the name of the block backend device to set the password on
#
-# @node-name: #optional graph node name to set the password on (Since 2.0)
+# @node-name: graph node name to set the password on (Since 2.0)
#
# @password: the password to use for the device
#
@@ -989,9 +989,9 @@
#
# Either @device or @node-name must be set but not both.
#
-# @device: #optional the name of the device to get the image resized
+# @device: the name of the device to get the image resized
#
-# @node-name: #optional graph node name to get the image resized (Since 2.0)
+# @node-name: graph node name to get the image resized (Since 2.0)
#
# @size: new image size in bytes
#
@@ -1033,19 +1033,19 @@
#
# Either @device or @node-name must be set but not both.
#
-# @device: #optional the name of the device to generate the snapshot from.
+# @device: the name of the device to generate the snapshot from.
#
-# @node-name: #optional graph node name to generate the snapshot from (Since 2.0)
+# @node-name: graph node name to generate the snapshot from (Since 2.0)
#
# @snapshot-file: the target of the new image. If the file exists, or
# if it is a device, the snapshot will be created in the existing
# file/device. Otherwise, a new file will be created.
#
-# @snapshot-node-name: #optional the graph node name of the new image (Since 2.0)
+# @snapshot-node-name: the graph node name of the new image (Since 2.0)
#
-# @format: #optional the format of the snapshot image, default is 'qcow2'.
+# @format: the format of the snapshot image, default is 'qcow2'.
#
-# @mode: #optional whether and how QEMU should create a new image, default is
+# @mode: whether and how QEMU should create a new image, default is
# 'absolute-paths'.
##
{ 'struct': 'BlockdevSnapshotSync',
@@ -1071,7 +1071,7 @@
##
# @DriveBackup:
#
-# @job-id: #optional identifier for the newly-created block job. If
+# @job-id: identifier for the newly-created block job. If
# omitted, the device name will be used. (Since 2.7)
#
# @device: the device name or node-name of a root node which should be copied.
@@ -1080,30 +1080,30 @@
# is a device, the existing file/device will be used as the new
# destination. If it does not exist, a new file will be created.
#
-# @format: #optional the format of the new destination, default is to
+# @format: the format of the new destination, default is to
# probe if @mode is 'existing', else the format of the source
#
# @sync: what parts of the disk image should be copied to the destination
# (all the disk, only the sectors allocated in the topmost image, from a
# dirty bitmap, or only new I/O).
#
-# @mode: #optional whether and how QEMU should create a new image, default is
+# @mode: whether and how QEMU should create a new image, default is
# 'absolute-paths'.
#
-# @speed: #optional the maximum speed, in bytes per second
+# @speed: the maximum speed, in bytes per second
#
-# @bitmap: #optional the name of dirty bitmap if sync is "incremental".
+# @bitmap: the name of dirty bitmap if sync is "incremental".
# Must be present if sync is "incremental", must NOT be present
# otherwise. (Since 2.4)
#
-# @compress: #optional true to compress data, if the target format supports it.
+# @compress: true to compress data, if the target format supports it.
# (default: false) (since 2.8)
#
-# @on-source-error: #optional the action to take on an error on the source,
+# @on-source-error: the action to take on an error on the source,
# default 'report'. 'stop' and 'enospc' can only be used
# if the block device supports io-status (see BlockInfo).
#
-# @on-target-error: #optional the action to take on an error on the target,
+# @on-target-error: the action to take on an error on the target,
# default 'report' (no limitations, since this applies to
# a different block device than @device).
#
@@ -1123,7 +1123,7 @@
##
# @BlockdevBackup:
#
-# @job-id: #optional identifier for the newly-created block job. If
+# @job-id: identifier for the newly-created block job. If
# omitted, the device name will be used. (Since 2.7)
#
# @device: the device name or node-name of a root node which should be copied.
@@ -1134,17 +1134,17 @@
# (all the disk, only the sectors allocated in the topmost image, or
# only new I/O).
#
-# @speed: #optional the maximum speed, in bytes per second. The default is 0,
+# @speed: the maximum speed, in bytes per second. The default is 0,
# for unlimited.
#
-# @compress: #optional true to compress data, if the target format supports it.
+# @compress: true to compress data, if the target format supports it.
# (default: false) (since 2.8)
#
-# @on-source-error: #optional the action to take on an error on the source,
+# @on-source-error: the action to take on an error on the source,
# default 'report'. 'stop' and 'enospc' can only be used
# if the block device supports io-status (see BlockInfo).
#
-# @on-target-error: #optional the action to take on an error on the target,
+# @on-target-error: the action to take on an error on the target,
# default 'report' (no limitations, since this applies to
# a different block device than @device).
#
@@ -1261,19 +1261,19 @@
# Live commit of data from overlay image nodes into backing nodes - i.e.,
# writes data between 'top' and 'base' into 'base'.
#
-# @job-id: #optional identifier for the newly-created block job. If
+# @job-id: identifier for the newly-created block job. If
# omitted, the device name will be used. (Since 2.7)
#
# @device: the device name or node-name of a root node
#
-# @base: #optional The file name of the backing image to write data into.
+# @base: The file name of the backing image to write data into.
# If not specified, this is the deepest backing image.
#
-# @top: #optional The file name of the backing image within the image chain,
+# @top: The file name of the backing image within the image chain,
# which contains the topmost data to be committed down. If
# not specified, this is the active layer.
#
-# @backing-file: #optional The backing file string to write into the overlay
+# @backing-file: The backing file string to write into the overlay
# image of 'top'. If 'top' is the active layer,
# specifying a backing file string is an error. This
# filename is not validated.
@@ -1302,9 +1302,9 @@
# size of the smaller top, you can safely truncate it
# yourself once the commit operation successfully completes.
#
-# @speed: #optional the maximum speed, in bytes per second
+# @speed: the maximum speed, in bytes per second
#
-# @filter-node-name: #optional the node name that should be assigned to the
+# @filter-node-name: the node name that should be assigned to the
# filter driver that the commit job inserts into the graph
# above @top. If this option is not given, a node name is
# autogenerated. (Since: 2.9)
@@ -1482,7 +1482,7 @@
#
# A set of parameters describing drive mirror setup.
#
-# @job-id: #optional identifier for the newly-created block job. If
+# @job-id: identifier for the newly-created block job. If
# omitted, the device name will be used. (Since 2.7)
#
# @device: the device name or node-name of a root node whose writes should be
@@ -1492,41 +1492,41 @@
# is a device, the existing file/device will be used as the new
# destination. If it does not exist, a new file will be created.
#
-# @format: #optional the format of the new destination, default is to
+# @format: the format of the new destination, default is to
# probe if @mode is 'existing', else the format of the source
#
-# @node-name: #optional the new block driver state node name in the graph
+# @node-name: the new block driver state node name in the graph
# (Since 2.1)
#
-# @replaces: #optional with sync=full graph node name to be replaced by the new
+# @replaces: with sync=full graph node name to be replaced by the new
# image when a whole image copy is done. This can be used to repair
# broken Quorum files. (Since 2.1)
#
-# @mode: #optional whether and how QEMU should create a new image, default is
+# @mode: whether and how QEMU should create a new image, default is
# 'absolute-paths'.
#
-# @speed: #optional the maximum speed, in bytes per second
+# @speed: the maximum speed, in bytes per second
#
# @sync: what parts of the disk image should be copied to the destination
# (all the disk, only the sectors allocated in the topmost image, or
# only new I/O).
#
-# @granularity: #optional granularity of the dirty bitmap, default is 64K
+# @granularity: granularity of the dirty bitmap, default is 64K
# if the image format doesn't have clusters, 4K if the clusters
# are smaller than that, else the cluster size. Must be a
# power of 2 between 512 and 64M (since 1.4).
#
-# @buf-size: #optional maximum amount of data in flight from source to
+# @buf-size: maximum amount of data in flight from source to
# target (since 1.4).
#
-# @on-source-error: #optional the action to take on an error on the source,
+# @on-source-error: the action to take on an error on the source,
# default 'report'. 'stop' and 'enospc' can only be used
# if the block device supports io-status (see BlockInfo).
#
-# @on-target-error: #optional the action to take on an error on the target,
+# @on-target-error: the action to take on an error on the target,
# default 'report' (no limitations, since this applies to
# a different block device than @device).
-# @unmap: #optional Whether to try to unmap target sectors where source has
+# @unmap: Whether to try to unmap target sectors where source has
# only zero. If true, and target unallocated sectors will read as zero,
# target image sectors will be unmapped; otherwise, zeroes will be
# written. Both will result in identical contents.
@@ -1562,7 +1562,7 @@
#
# @name: name of the dirty bitmap
#
-# @granularity: #optional the bitmap granularity, default is 64k for
+# @granularity: the bitmap granularity, default is 64k for
# block-dirty-bitmap-add
#
# Since: 2.4
@@ -1642,7 +1642,7 @@
#
# Start mirroring a block device's writes to a new destination.
#
-# @job-id: #optional identifier for the newly-created block job. If
+# @job-id: identifier for the newly-created block job. If
# omitted, the device name will be used. (Since 2.7)
#
# @device: The device name or node-name of a root node whose writes should be
@@ -1651,33 +1651,33 @@
# @target: the id or node-name of the block device to mirror to. This mustn't be
# attached to guest.
#
-# @replaces: #optional with sync=full graph node name to be replaced by the new
+# @replaces: with sync=full graph node name to be replaced by the new
# image when a whole image copy is done. This can be used to repair
# broken Quorum files.
#
-# @speed: #optional the maximum speed, in bytes per second
+# @speed: the maximum speed, in bytes per second
#
# @sync: what parts of the disk image should be copied to the destination
# (all the disk, only the sectors allocated in the topmost image, or
# only new I/O).
#
-# @granularity: #optional granularity of the dirty bitmap, default is 64K
+# @granularity: granularity of the dirty bitmap, default is 64K
# if the image format doesn't have clusters, 4K if the clusters
# are smaller than that, else the cluster size. Must be a
# power of 2 between 512 and 64M
#
-# @buf-size: #optional maximum amount of data in flight from source to
+# @buf-size: maximum amount of data in flight from source to
# target
#
-# @on-source-error: #optional the action to take on an error on the source,
+# @on-source-error: the action to take on an error on the source,
# default 'report'. 'stop' and 'enospc' can only be used
# if the block device supports io-status (see BlockInfo).
#
-# @on-target-error: #optional the action to take on an error on the target,
+# @on-target-error: the action to take on an error on the target,
# default 'report' (no limitations, since this applies to
# a different block device than @device).
#
-# @filter-node-name: #optional the node name that should be assigned to the
+# @filter-node-name: the node name that should be assigned to the
# filter driver that the mirror job inserts into the graph
# above @device. If this option is not given, a node name is
# autogenerated. (Since: 2.9)
@@ -1765,9 +1765,9 @@
#
# A set of parameters describing block throttling.
#
-# @device: #optional Block device name (deprecated, use @id instead)
+# @device: Block device name (deprecated, use @id instead)
#
-# @id: #optional The name or QOM path of the guest device (since: 2.8)
+# @id: The name or QOM path of the guest device (since: 2.8)
#
# @bps: total throughput limit in bytes per second
#
@@ -1781,57 +1781,57 @@
#
# @iops_wr: write I/O operations per second
#
-# @bps_max: #optional total throughput limit during bursts,
+# @bps_max: total throughput limit during bursts,
# in bytes (Since 1.7)
#
-# @bps_rd_max: #optional read throughput limit during bursts,
+# @bps_rd_max: read throughput limit during bursts,
# in bytes (Since 1.7)
#
-# @bps_wr_max: #optional write throughput limit during bursts,
+# @bps_wr_max: write throughput limit during bursts,
# in bytes (Since 1.7)
#
-# @iops_max: #optional total I/O operations per second during bursts,
+# @iops_max: total I/O operations per second during bursts,
# in bytes (Since 1.7)
#
-# @iops_rd_max: #optional read I/O operations per second during bursts,
+# @iops_rd_max: read I/O operations per second during bursts,
# in bytes (Since 1.7)
#
-# @iops_wr_max: #optional write I/O operations per second during bursts,
+# @iops_wr_max: write I/O operations per second during bursts,
# in bytes (Since 1.7)
#
-# @bps_max_length: #optional maximum length of the @bps_max burst
+# @bps_max_length: maximum length of the @bps_max burst
# period, in seconds. It must only
# be set if @bps_max is set as well.
# Defaults to 1. (Since 2.6)
#
-# @bps_rd_max_length: #optional maximum length of the @bps_rd_max
+# @bps_rd_max_length: maximum length of the @bps_rd_max
# burst period, in seconds. It must only
# be set if @bps_rd_max is set as well.
# Defaults to 1. (Since 2.6)
#
-# @bps_wr_max_length: #optional maximum length of the @bps_wr_max
+# @bps_wr_max_length: maximum length of the @bps_wr_max
# burst period, in seconds. It must only
# be set if @bps_wr_max is set as well.
# Defaults to 1. (Since 2.6)
#
-# @iops_max_length: #optional maximum length of the @iops burst
+# @iops_max_length: maximum length of the @iops burst
# period, in seconds. It must only
# be set if @iops_max is set as well.
# Defaults to 1. (Since 2.6)
#
-# @iops_rd_max_length: #optional maximum length of the @iops_rd_max
+# @iops_rd_max_length: maximum length of the @iops_rd_max
# burst period, in seconds. It must only
# be set if @iops_rd_max is set as well.
# Defaults to 1. (Since 2.6)
#
-# @iops_wr_max_length: #optional maximum length of the @iops_wr_max
+# @iops_wr_max_length: maximum length of the @iops_wr_max
# burst period, in seconds. It must only
# be set if @iops_wr_max is set as well.
# Defaults to 1. (Since 2.6)
#
-# @iops_size: #optional an I/O size in bytes (Since 1.7)
+# @iops_size: an I/O size in bytes (Since 1.7)
#
-# @group: #optional throttle group name (Since 2.4)
+# @group: throttle group name (Since 2.4)
#
# Since: 1.1
##
@@ -1872,18 +1872,18 @@
# On successful completion the image file is updated to drop the backing file
# and the BLOCK_JOB_COMPLETED event is emitted.
#
-# @job-id: #optional identifier for the newly-created block job. If
+# @job-id: identifier for the newly-created block job. If
# omitted, the device name will be used. (Since 2.7)
#
# @device: the device or node name of the top image
#
-# @base: #optional the common backing file name.
+# @base: the common backing file name.
# It cannot be set if @base-node is also set.
#
-# @base-node: #optional the node name of the backing file.
+# @base-node: the node name of the backing file.
# It cannot be set if @base is also set. (Since 2.8)
#
-# @backing-file: #optional The backing file string to write into the top
+# @backing-file: The backing file string to write into the top
# image. This filename is not validated.
#
# If a pathname string is such that it cannot be
@@ -1898,9 +1898,9 @@
# protocol.
# (Since 2.1)
#
-# @speed: #optional the maximum speed, in bytes per second
+# @speed: the maximum speed, in bytes per second
#
-# @on-error: #optional the action to take on an error (default report).
+# @on-error: the action to take on an error (default report).
# 'stop' and 'enospc' can only be used if the block device
# supports io-status (see BlockInfo). Since 1.3.
#
@@ -1967,7 +1967,7 @@
# the name of the parameter), but since QEMU 2.7 it can have
# other values.
#
-# @force: #optional whether to allow cancellation of a paused job (default
+# @force: whether to allow cancellation of a paused job (default
# false). Since 1.3.
#
# Returns: Nothing on success
@@ -2099,9 +2099,9 @@
#
# Includes cache-related options for block devices
#
-# @direct: #optional enables use of O_DIRECT (bypass the host page cache;
+# @direct: enables use of O_DIRECT (bypass the host page cache;
# default: false)
-# @no-flush: #optional ignore any flush requests for the device (default:
+# @no-flush: ignore any flush requests for the device (default:
# false)
#
# Since: 1.7
@@ -2142,7 +2142,7 @@
# Driver specific block device options for the file backend.
#
# @filename: path to the image file
-# @aio: #optional AIO backend (default: threads) (since: 2.8)
+# @aio: AIO backend (default: threads) (since: 2.8)
#
# Since: 1.7
##
@@ -2155,8 +2155,8 @@
#
# Driver specific block device options for the null backend.
#
-# @size: #optional size of the device in bytes.
-# @latency-ns: #optional emulated latency (in nanoseconds) in processing
+# @size: size of the device in bytes.
+# @latency-ns: emulated latency (in nanoseconds) in processing
# requests. Default to zero which completes requests immediately.
# (Since 2.4)
#
@@ -2171,14 +2171,14 @@
# Driver specific block device options for the vvfat protocol.
#
# @dir: directory to be exported as FAT image
-# @fat-type: #optional FAT type: 12, 16 or 32
-# @floppy: #optional whether to export a floppy image (true) or
+# @fat-type: FAT type: 12, 16 or 32
+# @floppy: whether to export a floppy image (true) or
# partitioned hard disk (false; default)
-# @label: #optional set the volume label, limited to 11 bytes. FAT16 and
+# @label: set the volume label, limited to 11 bytes. FAT16 and
# FAT32 traditionally have some restrictions on labels, which are
# ignored by most operating systems. Defaults to "QEMU VVFAT".
# (since 2.4)
-# @rw: #optional whether to allow write operations (default: false)
+# @rw: whether to allow write operations (default: false)
#
# Since: 1.7
##
@@ -2204,7 +2204,7 @@
#
# Driver specific block device options for LUKS.
#
-# @key-secret: #optional the ID of a QCryptoSecret object providing
+# @key-secret: the ID of a QCryptoSecret object providing
# the decryption key (since 2.6). Mandatory except when
# doing a metadata-only probe of the image.
#
@@ -2221,7 +2221,7 @@
# Driver specific block device options for image format that have no option
# besides their data source and an optional backing file.
#
-# @backing: #optional reference to or definition of the backing file block
+# @backing: reference to or definition of the backing file block
# device (if missing, taken from the image file content). It is
# allowed to pass an empty string here in order to disable the
# default backing file.
@@ -2297,33 +2297,33 @@
#
# Driver specific block device options for qcow2.
#
-# @lazy-refcounts: #optional whether to enable the lazy refcounts
+# @lazy-refcounts: whether to enable the lazy refcounts
# feature (default is taken from the image file)
#
-# @pass-discard-request: #optional whether discard requests to the qcow2
+# @pass-discard-request: whether discard requests to the qcow2
# device should be forwarded to the data source
#
-# @pass-discard-snapshot: #optional whether discard requests for the data source
+# @pass-discard-snapshot: whether discard requests for the data source
# should be issued when a snapshot operation (e.g.
# deleting a snapshot) frees clusters in the qcow2 file
#
-# @pass-discard-other: #optional whether discard requests for the data source
+# @pass-discard-other: whether discard requests for the data source
# should be issued on other occasions where a cluster
# gets freed
#
-# @overlap-check: #optional which overlap checks to perform for writes
+# @overlap-check: which overlap checks to perform for writes
# to the image, defaults to 'cached' (since 2.2)
#
-# @cache-size: #optional the maximum total size of the L2 table and
+# @cache-size: the maximum total size of the L2 table and
# refcount block caches in bytes (since 2.2)
#
-# @l2-cache-size: #optional the maximum size of the L2 table cache in
+# @l2-cache-size: the maximum size of the L2 table cache in
# bytes (since 2.2)
#
-# @refcount-cache-size: #optional the maximum size of the refcount block cache
+# @refcount-cache-size: the maximum size of the refcount block cache
# in bytes (since 2.2)
#
-# @cache-clean-interval: #optional clean unused entries in the L2 and refcount
+# @cache-clean-interval: clean unused entries in the L2 and refcount
# caches. The interval is in seconds. The default value
# is 0 and it disables this feature (since 2.5)
#
@@ -2349,17 +2349,17 @@
#
# @volume: Name of the Archipelago volume image
#
-# @mport: #optional The port number on which mapperd is
+# @mport: The port number on which mapperd is
# listening. This is optional
# and if not specified, QEMU will make Archipelago
# use the default port (1001).
#
-# @vport: #optional The port number on which vlmcd is
+# @vport: The port number on which vlmcd is
# listening. This is optional
# and if not specified, QEMU will make Archipelago
# use the default port (501).
#
-# @segment: #optional The name of the shared memory segment
+# @segment: The name of the shared memory segment
# Archipelago stack is using. This is optional
# and if not specified, QEMU will make Archipelago
# use the default value, 'archipelago'.
@@ -2378,7 +2378,7 @@
#
# @path: path to the image on the host
#
-# @user: #optional user as which to connect, defaults to current
+# @user: user as which to connect, defaults to current
# local user name
#
# TODO: Expose the host_key_check option in QMP
@@ -2421,20 +2421,20 @@
#
# @event: trigger event
#
-# @state: #optional the state identifier blkdebug needs to be in to
+# @state: the state identifier blkdebug needs to be in to
# actually trigger the event; defaults to "any"
#
-# @errno: #optional error identifier (errno) to be returned; defaults to
+# @errno: error identifier (errno) to be returned; defaults to
# EIO
#
-# @sector: #optional specifies the sector index which has to be affected
+# @sector: specifies the sector index which has to be affected
# in order to actually trigger the event; defaults to "any
# sector"
#
-# @once: #optional disables further events after this one has been
+# @once: disables further events after this one has been
# triggered; defaults to false
#
-# @immediately: #optional fail immediately; defaults to false
+# @immediately: fail immediately; defaults to false
#
# Since: 2.0
##
@@ -2453,7 +2453,7 @@
#
# @event: trigger event
#
-# @state: #optional the current state identifier blkdebug needs to be in;
+# @state: the current state identifier blkdebug needs to be in;
# defaults to "any"
#
# @new_state: the state identifier blkdebug is supposed to assume if
@@ -2473,14 +2473,14 @@
#
# @image: underlying raw block device (or image file)
#
-# @config: #optional filename of the configuration file
+# @config: filename of the configuration file
#
-# @align: #optional required alignment for requests in bytes,
+# @align: required alignment for requests in bytes,
# must be power of 2, or 0 for default
#
-# @inject-error: #optional array of error injection descriptions
+# @inject-error: array of error injection descriptions
#
-# @set-state: #optional array of state-change descriptions
+# @set-state: array of state-change descriptions
#
# Since: 2.0
##
@@ -2524,17 +2524,17 @@
#
# Driver specific block device options for Quorum
#
-# @blkverify: #optional true if the driver must print content mismatch
+# @blkverify: true if the driver must print content mismatch
# set to false by default
#
# @children: the children block devices to use
#
# @vote-threshold: the vote limit under which a read will fail
#
-# @rewrite-corrupted: #optional rewrite corrupted data when quorum is reached
+# @rewrite-corrupted: rewrite corrupted data when quorum is reached
# (Since 2.1)
#
-# @read-pattern: #optional choose read pattern and set to quorum by default
+# @read-pattern: choose read pattern and set to quorum by default
# (Since 2.2)
#
# Since: 2.0
@@ -2557,10 +2557,10 @@
#
# @server: gluster servers description
#
-# @debug: #optional libgfapi log level (default '4' which is Error)
+# @debug: libgfapi log level (default '4' which is Error)
# (Since 2.8)
#
-# @logfile: #optional libgfapi log file (default /dev/stderr) (Since 2.8)
+# @logfile: libgfapi log file (default /dev/stderr) (Since 2.8)
#
# Since: 2.7
##
@@ -2601,23 +2601,23 @@
#
# @target: The target iqn name
#
-# @lun: #optional LUN to connect to. Defaults to 0.
+# @lun: LUN to connect to. Defaults to 0.
#
-# @user: #optional User name to log in with. If omitted, no CHAP
+# @user: User name to log in with. If omitted, no CHAP
# authentication is performed.
#
-# @password-secret: #optional The ID of a QCryptoSecret object providing
+# @password-secret: The ID of a QCryptoSecret object providing
# the password for the login. This option is required if
# @user is specified.
#
-# @initiator-name: #optional The iqn name we want to identify to the target
+# @initiator-name: The iqn name we want to identify to the target
# as. If this option is not specified, an initiator name is
# generated automatically.
#
-# @header-digest: #optional The desired header digest. Defaults to
+# @header-digest: The desired header digest. Defaults to
# none-crc32c.
#
-# @timeout: #optional Timeout in seconds after which a request will
+# @timeout: Timeout in seconds after which a request will
# timeout. 0 means no timeout and is the default.
#
# Driver specific block device options for iscsi
@@ -2664,20 +2664,20 @@
#
# @image: Image name in the Ceph pool.
#
-# @conf: #optional path to Ceph configuration file. Values
+# @conf: path to Ceph configuration file. Values
# in the configuration file will be overridden by
# options specified via QAPI.
#
-# @snapshot: #optional Ceph snapshot name.
+# @snapshot: Ceph snapshot name.
#
-# @user: #optional Ceph id name.
+# @user: Ceph id name.
#
-# @server: #optional Monitor host address and port. This maps
+# @server: Monitor host address and port. This maps
# to the "mon_host" Ceph option.
#
-# @auth-supported: #optional Authentication supported.
+# @auth-supported: Authentication supported.
#
-# @password-secret: #optional The ID of a QCryptoSecret object providing
+# @password-secret: The ID of a QCryptoSecret object providing
# the password for the login.
#
# Since: 2.9
@@ -2732,7 +2732,7 @@
#
# @mode: the replication mode
#
-# @top-id: #optional In secondary mode, node name or device ID of the root
+# @top-id: In secondary mode, node name or device ID of the root
# node who owns the replication node chain. Must not be given in
# primary mode.
#
@@ -2779,24 +2779,24 @@
#
# @path: path of the image on the host
#
-# @user: #optional UID value to use when talking to the
+# @user: UID value to use when talking to the
# server (defaults to 65534 on Windows and getuid()
# on unix)
#
-# @group: #optional GID value to use when talking to the
+# @group: GID value to use when talking to the
# server (defaults to 65534 on Windows and getgid()
# in unix)
#
-# @tcp-syn-count: #optional number of SYNs during the session
+# @tcp-syn-count: number of SYNs during the session
# establishment (defaults to libnfs default)
#
-# @readahead-size: #optional set the readahead size in bytes (defaults
+# @readahead-size: set the readahead size in bytes (defaults
# to libnfs default)
#
-# @page-cache-size: #optional set the pagecache size in bytes (defaults
+# @page-cache-size: set the pagecache size in bytes (defaults
# to libnfs default)
#
-# @debug: #optional set the NFS debug level (max 2) (defaults
+# @debug: set the NFS debug level (max 2) (defaults
# to libnfs default)
#
# Since: 2.8
@@ -2830,9 +2830,9 @@
#
# @server: NBD server address
#
-# @export: #optional export name
+# @export: export name
#
-# @tls-creds: #optional TLS credentials ID
+# @tls-creds: TLS credentials ID
#
# Since: 2.8
##
@@ -2846,8 +2846,8 @@
#
# Driver specific block device options for the raw driver.
#
-# @offset: #optional position where the block device starts
-# @size: #optional the assumed size of the device
+# @offset: position where the block device starts
+# @size: the assumed size of the device
#
# Since: 2.8
##
@@ -2862,13 +2862,13 @@
# block devices, independent of the block driver:
#
# @driver: block driver name
-# @node-name: #optional the node name of the new node (Since 2.0).
+# @node-name: the node name of the new node (Since 2.0).
# This option is required on the top level of blockdev-add.
-# @discard: #optional discard-related options (default: ignore)
-# @cache: #optional cache-related options
-# @read-only: #optional whether the block device should be read-only
+# @discard: discard-related options (default: ignore)
+# @cache: cache-related options
+# @read-only: whether the block device should be read-only
# (default: false)
-# @detect-zeroes: #optional detect and optimize zero writes (Since 2.1)
+# @detect-zeroes: detect and optimize zero writes (Since 2.1)
# (default: off)
#
# Remaining options are determined by the block driver.
@@ -3050,11 +3050,11 @@
# to it
# - if the guest device does not have an actual tray
#
-# @device: #optional Block device name (deprecated, use @id instead)
+# @device: Block device name (deprecated, use @id instead)
#
-# @id: #optional The name or QOM path of the guest device (since: 2.8)
+# @id: The name or QOM path of the guest device (since: 2.8)
#
-# @force: #optional if false (the default), an eject request will be sent to
+# @force: if false (the default), an eject request will be sent to
# the guest if it has locked the tray (and the tray will not be opened
# immediately); if true, the tray will be opened regardless of whether
# it is locked
@@ -3090,9 +3090,9 @@
#
# If the tray was already closed before, this will be a no-op.
#
-# @device: #optional Block device name (deprecated, use @id instead)
+# @device: Block device name (deprecated, use @id instead)
#
-# @id: #optional The name or QOM path of the guest device (since: 2.8)
+# @id: The name or QOM path of the guest device (since: 2.8)
#
# Since: 2.5
#
@@ -3124,9 +3124,9 @@
#
# If the tray is open and there is no medium inserted, this will be a no-op.
#
-# @device: #optional Block device name (deprecated, use @id instead)
+# @device: Block device name (deprecated, use @id instead)
#
-# @id: #optional The name or QOM path of the guest device (since: 2.8)
+# @id: The name or QOM path of the guest device (since: 2.8)
#
# Note: This command is still a work in progress and is considered experimental.
# Stay away from it unless you want to help with its development.
@@ -3170,9 +3170,9 @@
# device's tray must currently be open (unless there is no attached guest
# device) and there must be no medium inserted already.
#
-# @device: #optional Block device name (deprecated, use @id instead)
+# @device: Block device name (deprecated, use @id instead)
#
-# @id: #optional The name or QOM path of the guest device (since: 2.8)
+# @id: The name or QOM path of the guest device (since: 2.8)
#
# @node-name: name of a node in the block driver state graph
#
@@ -3231,17 +3231,17 @@
# combines blockdev-open-tray, x-blockdev-remove-medium,
# x-blockdev-insert-medium and blockdev-close-tray).
#
-# @device: #optional Block device name (deprecated, use @id instead)
+# @device: Block device name (deprecated, use @id instead)
#
-# @id: #optional The name or QOM path of the guest device
+# @id: The name or QOM path of the guest device
# (since: 2.8)
#
# @filename: filename of the new image to be loaded
#
-# @format: #optional format to open the new image with (defaults to
+# @format: format to open the new image with (defaults to
# the probed format)
#
-# @read-only-mode: #optional change the read-only mode of the device; defaults
+# @read-only-mode: change the read-only mode of the device; defaults
# to 'retain'
#
# Since: 2.5
@@ -3314,16 +3314,16 @@
# reasons, but it can be empty ("") if the image does not
# have a device name associated.
#
-# @node-name: #optional node name (Since: 2.4)
+# @node-name: node name (Since: 2.4)
#
# @msg: informative message for human consumption, such as the kind of
# corruption being detected. It should not be parsed by machine as it is
# not guaranteed to be stable
#
-# @offset: #optional if the corruption resulted from an image access, this is
+# @offset: if the corruption resulted from an image access, this is
# the host's access offset into the image
#
-# @size: #optional if the corruption resulted from an image access, this is
+# @size: if the corruption resulted from an image access, this is
# the access size
#
# @fatal: if set, the image is marked corrupt and therefore unusable after this
@@ -3368,7 +3368,7 @@
#
# @action: action that has been taken
#
-# @nospace: #optional true if I/O error was caused due to a no-space
+# @nospace: true if I/O error was caused due to a no-space
# condition. This key is only present if query-block's
# io-status is present, please see query-block documentation
# for more information (since: 2.2)
@@ -3414,7 +3414,7 @@
#
# @speed: rate limit, bytes per second
#
-# @error: #optional error message. Only present on failure. This field
+# @error: error message. Only present on failure. This field
# contains a human-readable error message. There are no semantics
# other than that streaming has failed and clients should not try to
# interpret the error string
@@ -3623,9 +3623,9 @@
#
# @parent: the id or name of the parent node.
#
-# @child: #optional the name of a child under the given parent node.
+# @child: the name of a child under the given parent node.
#
-# @node: #optional the name of the node that will be added.
+# @node: the name of the node that will be added.
#
# Note: this command is experimental, and its API is not stable. It
# does not support all kinds of operations, all kinds of children, nor
diff --git a/qapi/block.json b/qapi/block.json
index 22da914..46fca0e 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -163,11 +163,11 @@
#
# Ejects a device from a removable drive.
#
-# @device: #optional Block device name (deprecated, use @id instead)
+# @device: Block device name (deprecated, use @id instead)
#
-# @id: #optional The name or QOM path of the guest device (since: 2.8)
+# @id: The name or QOM path of the guest device (since: 2.8)
#
-# @force: #optional If true, eject regardless of whether the drive is locked.
+# @force: If true, eject regardless of whether the drive is locked.
# If not specified, the default value is false.
#
# Returns: Nothing on success
@@ -215,7 +215,7 @@
# @device: The device name or node name of the node to be exported
#
# @writable: Whether clients should be able to write to the device via the
-# NBD connection (default false). #optional
+# NBD connection (default false).
#
# Returns: error if the device is already marked for export.
#
diff --git a/qapi/crypto.json b/qapi/crypto.json
index 93a0474..6b6fde3 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -152,7 +152,7 @@
#
# The options that apply to QCow/QCow2 AES-CBC encryption format
#
-# @key-secret: #optional the ID of a QCryptoSecret object providing the
+# @key-secret: the ID of a QCryptoSecret object providing the
# decryption key. Mandatory except when probing image for
# metadata only.
#
@@ -166,7 +166,7 @@
#
# The options that apply to LUKS encryption format
#
-# @key-secret: #optional the ID of a QCryptoSecret object providing the
+# @key-secret: the ID of a QCryptoSecret object providing the
# decryption key. Mandatory except when probing image for
# metadata only.
# Since: 2.6
@@ -180,17 +180,17 @@
#
# The options that apply to LUKS encryption format initialization
#
-# @cipher-alg: #optional the cipher algorithm for data encryption
+# @cipher-alg: the cipher algorithm for data encryption
# Currently defaults to 'aes'.
-# @cipher-mode: #optional the cipher mode for data encryption
+# @cipher-mode: the cipher mode for data encryption
# Currently defaults to 'cbc'
-# @ivgen-alg: #optional the initialization vector generator
+# @ivgen-alg: the initialization vector generator
# Currently defaults to 'essiv'
-# @ivgen-hash-alg: #optional the initialization vector generator hash
+# @ivgen-hash-alg: the initialization vector generator hash
# Currently defaults to 'sha256'
-# @hash-alg: #optional the master key hash algorithm
+# @hash-alg: the master key hash algorithm
# Currently defaults to 'sha256'
-# @iter-time: #optional number of milliseconds to spend in
+# @iter-time: number of milliseconds to spend in
# PBKDF passphrase processing. Currently defaults
# to 2000. (since 2.8)
# Since: 2.6
@@ -257,8 +257,8 @@
#
# @active: whether the key slot is currently in use
# @key-offset: offset to the key material in bytes
-# @iters: #optional number of PBKDF2 iterations for key material
-# @stripes: #optional number of stripes for splitting key material
+# @iters: number of PBKDF2 iterations for key material
+# @stripes: number of stripes for splitting key material
#
# Since: 2.7
##
@@ -277,7 +277,7 @@
# @cipher-alg: the cipher algorithm for data encryption
# @cipher-mode: the cipher mode for data encryption
# @ivgen-alg: the initialization vector generator
-# @ivgen-hash-alg: #optional the initialization vector generator hash
+# @ivgen-hash-alg: the initialization vector generator hash
# @hash-alg: the master key hash algorithm
# @payload-offset: offset to the payload data in bytes
# @master-key-iters: number of PBKDF2 iterations for key material
diff --git a/qapi/event.json b/qapi/event.json
index e02852c..e80f3f4 100644
--- a/qapi/event.json
+++ b/qapi/event.json
@@ -186,7 +186,7 @@
# At this point, it's safe to reuse the specified device ID. Device removal can
# be initiated by the guest or by HMP/QMP commands.
#
-# @device: #optional device name
+# @device: device name
#
# @path: device path
#
@@ -209,7 +209,7 @@
# Emitted once until the 'query-rx-filter' command is executed, the first event
# will always be emitted
#
-# @name: #optional net client name
+# @name: net client name
#
# @path: device path
#
@@ -488,7 +488,7 @@
#
# @action: action that has been taken, currently always "pause"
#
-# @info: #optional information about a panic (since 2.9)
+# @info: information about a panic (since 2.9)
#
# Since: 1.5
#
@@ -533,7 +533,7 @@
#
# @type: quorum operation type (Since 2.6)
#
-# @error: #optional error message. Only present on failure. This field
+# @error: error message. Only present on failure. This field
# contains a human-readable error message. There are no semantics other
# than that the block layer reported an error and clients should not
# try to interpret the error string.
@@ -620,7 +620,7 @@
#
# @result: DumpQueryResult type described in qapi-schema.json.
#
-# @error: #optional human-readable error string that provides
+# @error: human-readable error string that provides
# hint on why dump failed. Only presents on failure. The
# user should not try to interpret the error string.
#
diff --git a/qapi/introspect.json b/qapi/introspect.json
index f6adc43..1dbaef5 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -163,10 +163,10 @@
#
# @members: the object type's (non-variant) members, in no particular order.
#
-# @tag: #optional the name of the member serving as type tag.
+# @tag: the name of the member serving as type tag.
# An element of @members with this name must exist.
#
-# @variants: #optional variant members, i.e. additional members that
+# @variants: variant members, i.e. additional members that
# depend on the type tag's value. Present exactly when
# @tag is present. The variants are in no particular order,
# and may even differ from the order of the values of the
@@ -190,7 +190,7 @@
#
# @type: the name of the member's type.
#
-# @default: #optional default when used as command parameter.
+# @default: default when used as command parameter.
# If absent, the parameter is mandatory.
# If present, the value must be null. The parameter is
# optional, and behavior when it's missing is not specified
diff --git a/qapi/rocker.json b/qapi/rocker.json
index f374038..3587661 100644
--- a/qapi/rocker.json
+++ b/qapi/rocker.json
@@ -121,23 +121,23 @@
#
# @tbl-id: flow table ID
#
-# @in-pport: #optional physical input port
+# @in-pport: physical input port
#
-# @tunnel-id: #optional tunnel ID
+# @tunnel-id: tunnel ID
#
-# @vlan-id: #optional VLAN ID
+# @vlan-id: VLAN ID
#
-# @eth-type: #optional Ethernet header type
+# @eth-type: Ethernet header type
#
-# @eth-src: #optional Ethernet header source MAC address
+# @eth-src: Ethernet header source MAC address
#
-# @eth-dst: #optional Ethernet header destination MAC address
+# @eth-dst: Ethernet header destination MAC address
#
-# @ip-proto: #optional IP Header protocol field
+# @ip-proto: IP Header protocol field
#
-# @ip-tos: #optional IP header TOS field
+# @ip-tos: IP header TOS field
#
-# @ip-dst: #optional IP header destination address
+# @ip-dst: IP header destination address
#
# Note: optional members may or may not appear in the flow key
# depending if they're relevant to the flow key.
@@ -155,19 +155,19 @@
#
# Rocker switch OF-DPA flow mask
#
-# @in-pport: #optional physical input port
+# @in-pport: physical input port
#
-# @tunnel-id: #optional tunnel ID
+# @tunnel-id: tunnel ID
#
-# @vlan-id: #optional VLAN ID
+# @vlan-id: VLAN ID
#
-# @eth-src: #optional Ethernet header source MAC address
+# @eth-src: Ethernet header source MAC address
#
-# @eth-dst: #optional Ethernet header destination MAC address
+# @eth-dst: Ethernet header destination MAC address
#
-# @ip-proto: #optional IP Header protocol field
+# @ip-proto: IP Header protocol field
#
-# @ip-tos: #optional IP header TOS field
+# @ip-tos: IP header TOS field
#
# Note: optional members may or may not appear in the flow mask
# depending if they're relevant to the flow mask.
@@ -184,17 +184,17 @@
#
# Rocker switch OF-DPA flow action
#
-# @goto-tbl: #optional next table ID
+# @goto-tbl: next table ID
#
-# @group-id: #optional group ID
+# @group-id: group ID
#
-# @tunnel-lport: #optional tunnel logical port ID
+# @tunnel-lport: tunnel logical port ID
#
-# @vlan-id: #optional VLAN ID
+# @vlan-id: VLAN ID
#
-# @new-vlan-id: #optional new VLAN ID
+# @new-vlan-id: new VLAN ID
#
-# @out-pport: #optional physical output port
+# @out-pport: physical output port
#
# Note: optional members may or may not appear in the flow action
# depending if they're relevant to the flow action.
@@ -234,7 +234,7 @@
#
# @name: switch name
#
-# @tbl-id: #optional flow table ID. If tbl-id is not specified, returns
+# @tbl-id: flow table ID. If tbl-id is not specified, returns
# flow information for all tables.
#
# Returns: rocker OF-DPA flow information
@@ -268,27 +268,27 @@
#
# @type: group type
#
-# @vlan-id: #optional VLAN ID
+# @vlan-id: VLAN ID
#
-# @pport: #optional physical port number
+# @pport: physical port number
#
-# @index: #optional group index, unique with group type
+# @index: group index, unique with group type
#
-# @out-pport: #optional output physical port number
+# @out-pport: output physical port number
#
-# @group-id: #optional next group ID
+# @group-id: next group ID
#
-# @set-vlan-id: #optional VLAN ID to set
+# @set-vlan-id: VLAN ID to set
#
-# @pop-vlan: #optional pop VLAN headr from packet
+# @pop-vlan: pop VLAN headr from packet
#
-# @group-ids: #optional list of next group IDs
+# @group-ids: list of next group IDs
#
-# @set-eth-src: #optional set source MAC address in Ethernet header
+# @set-eth-src: set source MAC address in Ethernet header
#
-# @set-eth-dst: #optional set destination MAC address in Ethernet header
+# @set-eth-dst: set destination MAC address in Ethernet header
#
-# @ttl-check: #optional perform TTL check
+# @ttl-check: perform TTL check
#
# Note: optional members may or may not appear in the group depending
# if they're relevant to the group type.
@@ -310,7 +310,7 @@
#
# @name: switch name
#
-# @type: #optional group type. If type is not specified, returns
+# @type: group type. If type is not specified, returns
# group information for all group types.
#
# Returns: rocker OF-DPA group information
diff --git a/qapi/trace.json b/qapi/trace.json
index 2bfda7a..de6588d 100644
--- a/qapi/trace.json
+++ b/qapi/trace.json
@@ -48,7 +48,7 @@
# Query the state of events.
#
# @name: Event name pattern (case-sensitive glob).
-# @vcpu: #optional The vCPU to query (any by default; since 2.7).
+# @vcpu: The vCPU to query (any by default; since 2.7).
#
# Returns: a list of @TraceEventInfo for the matching events
#
@@ -81,8 +81,8 @@
#
# @name: Event name pattern (case-sensitive glob).
# @enable: Whether to enable tracing.
-# @ignore-unavailable: #optional Do not match unavailable events with @name.
-# @vcpu: #optional The vCPU to act upon (all by default; since 2.7).
+# @ignore-unavailable: Do not match unavailable events with @name.
+# @vcpu: The vCPU to act upon (all by default; since 2.7).
#
# An event's state is modified if:
# - its name matches the @name pattern, and
diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index a8e4bda..a02dbf2 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -144,7 +144,7 @@
# If that's the case users are advised to always pass a
# value.
#
-# @time: #optional time of nanoseconds, relative to the Epoch
+# @time: time of nanoseconds, relative to the Epoch
# of 1970-01-01 in UTC.
#
# Returns: Nothing on success.
@@ -203,7 +203,7 @@
# Initiate guest-activated shutdown. Note: this is an asynchronous
# shutdown request, with no guarantee of successful shutdown.
#
-# @mode: #optional "halt", "powerdown" (default), or "reboot"
+# @mode: "halt", "powerdown" (default), or "reboot"
#
# This command does NOT return a response on success. Success condition
# is indicated by the VM exiting with a zero exit status or, when
@@ -222,7 +222,7 @@
#
# @path: Full path to the file in the guest to open.
#
-# @mode: #optional open mode, as per fopen(), "r" is the default.
+# @mode: open mode, as per fopen(), "r" is the default.
#
# Returns: Guest file handle on success.
#
@@ -270,7 +270,7 @@
#
# @handle: filehandle returned by guest-file-open
#
-# @count: #optional maximum number of bytes to read (default is 4KB)
+# @count: maximum number of bytes to read (default is 4KB)
#
# Returns: @GuestFileRead on success.
#
@@ -304,7 +304,7 @@
#
# @buf-b64: base64-encoded string representing data to be written
#
-# @count: #optional bytes to write (actual bytes, after base64-decode),
+# @count: bytes to write (actual bytes, after base64-decode),
# default is all content in buf-b64 buffer after base64 decoding
#
# Returns: @GuestFileWrite on success.
@@ -441,7 +441,7 @@
#
# Sync and freeze specified guest filesystems
#
-# @mountpoints: #optional an array of mountpoints of filesystems to be frozen.
+# @mountpoints: an array of mountpoints of filesystems to be frozen.
# If omitted, every mounted filesystem is frozen.
#
# Returns: Number of file systems currently frozen. On error, all filesystems
@@ -670,7 +670,7 @@
#
# @online: Whether the VCPU is enabled.
#
-# @can-offline: #optional Whether offlining the VCPU is possible. This member
+# @can-offline: Whether offlining the VCPU is possible. This member
# is always filled in by the guest agent when the structure is
# returned, and always ignored on input (hence it can be omitted
# then).
@@ -858,7 +858,7 @@
#
# @online: Whether the MEMORY BLOCK is enabled in guest.
#
-# @can-offline: #optional Whether offlining the MEMORY BLOCK is possible.
+# @can-offline: Whether offlining the MEMORY BLOCK is possible.
# This member is always filled in by the guest agent when the
# structure is returned, and always ignored on input (hence it
# can be omitted then).
@@ -911,7 +911,7 @@
#
# @response: the result of memory block operation.
#
-# @error-code: #optional the error number.
+# @error-code: the error number.
# When memory block operation fails, we assign the value of
# 'errno' to this member, it indicates what goes wrong.
# When the operation succeeds, it will be omitted.
@@ -979,16 +979,16 @@
# @GuestExecStatus:
#
# @exited: true if process has already terminated.
-# @exitcode: #optional process exit code if it was normally terminated.
-# @signal: #optional signal number (linux) or unhandled exception code
+# @exitcode: process exit code if it was normally terminated.
+# @signal: signal number (linux) or unhandled exception code
# (windows) if the process was abnormally terminated.
-# @out-data: #optional base64-encoded stdout of the process
-# @err-data: #optional base64-encoded stderr of the process
+# @out-data: base64-encoded stdout of the process
+# @err-data: base64-encoded stderr of the process
# Note: @out-data and @err-data are present only
# if 'capture-output' was specified for 'guest-exec'
-# @out-truncated: #optional true if stdout was not fully captured
+# @out-truncated: true if stdout was not fully captured
# due to size limitation.
-# @err-truncated: #optional true if stderr was not fully captured
+# @err-truncated: true if stderr was not fully captured
# due to size limitation.
#
# Since: 2.5
@@ -1028,10 +1028,10 @@
# Execute a command in the guest
#
# @path: path or executable name to execute
-# @arg: #optional argument list to pass to executable
-# @env: #optional environment variables to pass to executable
-# @input-data: #optional data to be passed to process stdin (base64 encoded)
-# @capture-output: #optional bool flag to enable capture of
+# @arg: argument list to pass to executable
+# @env: environment variables to pass to executable
+# @input-data: data to be passed to process stdin (base64 encoded)
+# @capture-output: bool flag to enable capture of
# stdout/stderr of running process. defaults to false.
#
# Returns: PID on success.
diff --git a/scripts/qapi.py b/scripts/qapi.py
index 2a2b33d..c580e76 100644
--- a/scripts/qapi.py
+++ b/scripts/qapi.py
@@ -219,6 +219,10 @@ class QAPIDoc(object):
if (in_arg or not self.section.name
or not self.section.name.startswith("Example")):
line = line.strip()
+ # TODO Drop this once the dust has settled
+ if (isinstance(self.section, QAPIDoc.ArgSection)
+ and '#optional' in line):
+ raise QAPISemError(self.info, "Please drop the #optional tag")
self.section.append(line)
def connect_member(self, member):
@@ -981,25 +985,6 @@ def check_definition_doc(doc, expr, info):
or (meta == 'union' and not expr.get('discriminator'))):
args.append('type')
- for arg in args:
- if arg[0] == '*':
- opt = True
- desc = doc.args.get(arg[1:])
- else:
- opt = False
- desc = doc.args.get(arg)
- if not desc:
- continue
- desc.optional = opt
- desc_opt = "#optional" in str(desc)
- if desc_opt and not opt:
- raise QAPISemError(info, "Description has #optional, "
- "but the declaration doesn't")
- if not desc_opt and opt:
- # TODO either fix the schema and make this an error,
- # or drop #optional entirely
- pass
-
doc_args = set(doc.args.keys())
args = set([name.strip('*') for name in args])
if not doc_args.issubset(args):
diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py
index 6d4e757..4583477 100755
--- a/scripts/qapi2texi.py
+++ b/scripts/qapi2texi.py
@@ -145,8 +145,7 @@ def texi_members(doc, member_func, show_undocumented):
for section in doc.args.itervalues():
if not section.content and not show_undocumented:
continue # Undocumented TODO require doc and drop
- desc = re.sub(r'^ *#optional *\n?|\n? *#optional *$|#optional',
- '', str(section))
+ desc = str(section)
items += member_func(section.member) + texi_format(desc) + '\n'
if not items:
return ''
diff --git a/tests/Makefile.include b/tests/Makefile.include
index 9f4e890..7230977 100644
--- a/tests/Makefile.include
+++ b/tests/Makefile.include
@@ -385,7 +385,6 @@ qapi-schema += doc-missing.json
qapi-schema += doc-missing-colon.json
qapi-schema += doc-missing-expr.json
qapi-schema += doc-missing-space.json
-qapi-schema += doc-optional.json
qapi-schema += double-data.json
qapi-schema += double-type.json
qapi-schema += duplicate-key.json
diff --git a/tests/qapi-schema/doc-optional.err b/tests/qapi-schema/doc-optional.err
deleted file mode 100644
index 20d405a..0000000
--- a/tests/qapi-schema/doc-optional.err
+++ /dev/null
@@ -1 +0,0 @@
-tests/qapi-schema/doc-optional.json:3: Description has #optional, but the declaration doesn't
diff --git a/tests/qapi-schema/doc-optional.exit b/tests/qapi-schema/doc-optional.exit
deleted file mode 100644
index d00491f..0000000
--- a/tests/qapi-schema/doc-optional.exit
+++ /dev/null
@@ -1 +0,0 @@
-1
diff --git a/tests/qapi-schema/doc-optional.json b/tests/qapi-schema/doc-optional.json
deleted file mode 100644
index 06c855e..0000000
--- a/tests/qapi-schema/doc-optional.json
+++ /dev/null
@@ -1,7 +0,0 @@
-# Description #optional should match declaration
-
-##
-# @foo:
-# @a: a #optional
-##
-{ 'command': 'foo', 'data': {'a': 'int'} }
diff --git a/tests/qapi-schema/doc-optional.out b/tests/qapi-schema/doc-optional.out
deleted file mode 100644
index e69de29..0000000
--
2.7.4
next prev parent reply other threads:[~2017-03-13 6:19 UTC|newest]
Thread overview: 137+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-03-13 6:18 [Qemu-devel] [PATCH for-2.9 00/47] qapi: Put type information back into QMP documentation Markus Armbruster
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 01/47] qapi: Factor QAPISchemaParser._include() out of .__init__() Markus Armbruster
2017-03-13 19:34 ` Eric Blake
2017-03-14 8:28 ` Marc-André Lureau
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 02/47] qapi: Make doc comments optional where we don't need them Markus Armbruster
2017-03-13 21:00 ` Eric Blake
2017-03-14 7:21 ` Markus Armbruster
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 03/47] qapi: Back out doc comments added just to please qapi.py Markus Armbruster
2017-03-13 21:13 ` Eric Blake
2017-03-14 7:26 ` Markus Armbruster
2017-03-14 8:28 ` Marc-André Lureau
2017-03-14 9:45 ` Markus Armbruster
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 04/47] docs/qapi-code-gen.txt: Drop confusing reference to 'gen' Markus Armbruster
2017-03-13 22:17 ` Eric Blake
2017-03-14 8:30 ` Marc-André Lureau
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 05/47] qapi: Have each QAPI schema declare its returns white-list Markus Armbruster
2017-03-13 22:41 ` Eric Blake
2017-03-14 7:40 ` Markus Armbruster
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 06/47] qapi: Have each QAPI schema declare its name rule violations Markus Armbruster
2017-03-13 22:46 ` Eric Blake
2017-03-14 7:51 ` Markus Armbruster
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 07/47] qapi: Clean up build of generated documentation Markus Armbruster
2017-03-14 15:55 ` Eric Blake
2017-03-15 7:08 ` Markus Armbruster
2017-03-15 11:53 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 08/47] tests/qapi-schema: Cover empty union base Markus Armbruster
2017-03-14 8:41 ` Marc-André Lureau
2017-03-14 15:56 ` Eric Blake
2017-03-15 7:11 ` Markus Armbruster
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 09/47] qapi: Fix to reject empty union base gracefully Markus Armbruster
2017-03-14 8:40 ` Marc-André Lureau
2017-03-14 15:58 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 10/47] qapi2texi: Fix up output around #optional Markus Armbruster
2017-03-14 8:37 ` Marc-André Lureau
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 11/47] qapi: Avoid unwanted blank lines in QAPIDoc Markus Armbruster
2017-03-14 8:46 ` Marc-André Lureau
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 12/47] qapi/rocker: Fix up doc comment notes on optional members Markus Armbruster
2017-03-14 8:49 ` Marc-André Lureau
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 13/47] qapi: Fix QAPISchemaEnumType.is_implicit() for 'QType' Markus Armbruster
2017-03-14 16:03 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 14/47] qapi: Prepare for requiring more complete documentation Markus Armbruster
2017-03-14 16:08 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 15/47] qapi: Conjure up QAPIDoc.ArgSection for undocumented members Markus Armbruster
2017-03-14 17:16 ` Eric Blake
2017-03-15 7:12 ` Markus Armbruster
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 16/47] qapi2texi: Convert to QAPISchemaVisitor Markus Armbruster
2017-03-14 17:31 ` Eric Blake
2017-03-15 7:14 ` Markus Armbruster
2017-03-13 6:18 ` Markus Armbruster [this message]
2017-03-14 17:59 ` [Qemu-devel] [PATCH for-2.9 17/47] qapi: The #optional tag is redundant, drop Eric Blake
2017-03-15 7:22 ` Markus Armbruster
2017-03-14 20:14 ` Eric Blake
2017-03-15 7:15 ` Markus Armbruster
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 18/47] qapi: Use raw strings for regular expressions consistently Markus Armbruster
2017-03-14 18:00 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 19/47] qapi: Prefer single-quoted strings more consistently Markus Armbruster
2017-03-14 18:05 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 20/47] qapi2texi: Plainer enum value and member name formatting Markus Armbruster
2017-03-14 18:06 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 21/47] qapi2texi: Present the table of members more clearly Markus Armbruster
2017-03-14 18:08 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 22/47] qapi2texi: Explain enum value undocumentedness " Markus Armbruster
2017-03-14 19:00 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 23/47] qapi2texi: Don't hide undocumented members and arguments Markus Armbruster
2017-03-14 19:02 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 24/47] qapi2texi: Implement boxed argument documentation Markus Armbruster
2017-03-14 19:12 ` Eric Blake
2017-03-15 7:23 ` Markus Armbruster
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 25/47] qapi2texi: Include member type in generated documentation Markus Armbruster
2017-03-14 12:42 ` Marc-André Lureau
2017-03-14 15:16 ` Markus Armbruster
2017-03-14 19:16 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 26/47] qapi2texi: Generate reference to base type members Markus Armbruster
2017-03-14 19:29 ` Eric Blake
2017-03-15 7:30 ` Markus Armbruster
2017-03-15 12:13 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 27/47] qapi2texi: Generate documentation for variant members Markus Armbruster
2017-03-14 19:36 ` Eric Blake
2017-03-15 7:36 ` Markus Armbruster
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 28/47] qapi2texi: Generate descriptions for simple union tags Markus Armbruster
2017-03-14 19:54 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 29/47] qapi2texi: Use category "Object" for all object types Markus Armbruster
2017-03-14 19:56 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 30/47] tests/qapi-schema: Improve doc / expression mismatch coverage Markus Armbruster
2017-03-14 20:02 ` Eric Blake
2017-03-14 20:36 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 31/47] qapi: Fix detection of doc / expression mismatch Markus Armbruster
2017-03-14 20:35 ` Eric Blake
2017-03-15 7:39 ` Markus Armbruster
2017-03-15 12:14 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 32/47] qapi: Move detection of doc / expression name mismatch Markus Armbruster
2017-03-14 20:43 ` Eric Blake
2017-03-15 7:39 ` Markus Armbruster
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 33/47] qapi: Improve error message on @NAME: in free-form doc Markus Armbruster
2017-03-14 20:46 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 34/47] qapi: Move empty doc section checking to doc parser Markus Armbruster
2017-03-13 6:23 ` Markus Armbruster
2017-03-15 1:40 ` Eric Blake
2017-03-15 7:44 ` Markus Armbruster
2017-03-15 1:37 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 35/47] tests/qapi-schema: Rename doc-bad-args to doc-bad-command-arg Markus Armbruster
2017-03-14 20:47 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 36/47] tests/qapi-schema: Improve coverage of bogus member docs Markus Armbruster
2017-03-14 20:55 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 37/47] qapi: Fix detection of bogus member documentation Markus Armbruster
2017-03-14 20:58 ` Eric Blake
2017-03-15 7:46 ` Markus Armbruster
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 38/47] qapi: Eliminate check_docs() and drop QAPIDoc.expr Markus Armbruster
2017-03-14 21:00 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 39/47] qapi: Drop unused variable events Markus Armbruster
2017-03-14 21:02 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 40/47] qapi: Simplify what gets stored in enum_types Markus Armbruster
2017-03-15 0:34 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 41/47] qapi: Factor add_name() calls out of the meta conditional Markus Armbruster
2017-03-15 0:39 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 42/47] qapi: enum_types is a list used like a dict, make it one Markus Armbruster
2017-03-15 0:47 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 43/47] qapi: struct_types " Markus Armbruster
2017-03-15 1:31 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 44/47] qapi: union_types " Markus Armbruster
2017-03-15 1:34 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 45/47] qapi: Drop unused .check_clash() parameter schema Markus Armbruster
2017-03-15 1:46 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 46/47] qapi: Make pylint a bit happier Markus Armbruster
2017-03-15 1:47 ` Eric Blake
2017-03-13 6:18 ` [Qemu-devel] [PATCH for-2.9 47/47] qapi: Fix a misleading parser error message Markus Armbruster
2017-03-15 1:48 ` Eric Blake
2017-03-13 10:32 ` [Qemu-devel] [PATCH for-2.9 00/47] qapi: Put type information back into QMP documentation Marc-André Lureau
2017-03-13 12:14 ` Markus Armbruster
2017-03-13 12:21 ` Marc-André Lureau
2017-03-13 13:12 ` Markus Armbruster
2017-03-14 13:22 ` Marc-André Lureau
2017-03-14 16:14 ` Markus Armbruster
2017-03-15 14:00 ` Marc-André Lureau
2017-03-14 13:24 ` Marc-André Lureau
2017-03-15 13:06 ` Markus Armbruster
2017-04-27 18:16 ` Eric Blake
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=1489385927-6735-18-git-send-email-armbru@redhat.com \
--to=armbru@redhat.com \
--cc=eblake@redhat.com \
--cc=marcandre.lureau@redhat.com \
--cc=mdroth@linux.vnet.ibm.com \
--cc=qemu-devel@nongnu.org \
/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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.