qapi: The #optional tag is redundant, drop

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>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <1489582656-31133-18-git-send-email-armbru@redhat.com>

18 files changed, 486 insertions, 516 deletions

diff --git a/docs/qapi-code-gen.txt b/docs/qapi-code-gen.txt
index 2f67900b4c..52e3874efe 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
+# @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,7 +166,7 @@ For example:
 #
 # Query the @BlockStats for all virtual block devices.
 #
-# @query-nodes: #optional If true, the command will query all the
+# @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 44c14db418..1e6375495b 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 52141cd51e..d693033556 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 786b39e911..1be1ec58ac 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
 #
@@ -253,7 +253,7 @@
 #       2.8: 'replication' added, 'tftp' dropped
 #       2.9: 'archipelago' 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)
 #
@@ -278,45 +278,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)
 #
@@ -411,7 +411,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
 #
@@ -441,17 +441,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
@@ -640,7 +640,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).
 #
@@ -690,19 +690,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
@@ -718,7 +718,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
@@ -957,9 +957,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
 #
@@ -990,9 +990,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
 #
@@ -1034,19 +1034,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',
@@ -1072,7 +1072,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.
@@ -1081,30 +1081,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).
 #
@@ -1124,7 +1124,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.
@@ -1135,17 +1135,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).
 #
@@ -1262,19 +1262,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.
@@ -1303,9 +1303,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)
@@ -1483,7 +1483,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
@@ -1493,41 +1493,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.
@@ -1563,7 +1563,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
@@ -1643,7 +1643,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
@@ -1652,33 +1652,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)
@@ -1766,9 +1766,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
 #
@@ -1782,57 +1782,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
 ##
@@ -1873,18 +1873,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
@@ -1899,9 +1899,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.
 #
@@ -1968,7 +1968,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
@@ -2100,9 +2100,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
@@ -2143,7 +2143,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
 ##
@@ -2156,8 +2156,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)
 #
@@ -2172,14 +2172,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
 ##
@@ -2205,7 +2205,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.
 #
@@ -2222,7 +2222,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.
@@ -2298,33 +2298,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)
 #
@@ -2350,7 +2350,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
@@ -2393,20 +2393,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
 ##
@@ -2425,7 +2425,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
@@ -2445,14 +2445,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
 ##
@@ -2496,17 +2496,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
@@ -2529,10 +2529,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
 ##
@@ -2573,23 +2573,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
@@ -2636,20 +2636,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
@@ -2704,7 +2704,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.
 #
@@ -2751,24 +2751,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
@@ -2802,9 +2802,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
 ##
@@ -2818,8 +2818,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
 ##
@@ -2834,13 +2834,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.
@@ -3021,11 +3021,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
@@ -3061,9 +3061,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
 #
@@ -3095,9 +3095,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.
@@ -3141,9 +3141,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
 #
@@ -3202,17 +3202,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
@@ -3285,16 +3285,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
@@ -3339,7 +3339,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)
@@ -3385,7 +3385,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
@@ -3594,9 +3594,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 22da91441b..46fca0e1f3 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 93a04743ea..6b6fde367a 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 e02852cd8a..e80f3f4446 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 f6adc439bb..1dbaef56eb 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 f374038c60..3587661161 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 2bfda7ac7c..de6588d9f7 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 a8e4bdabc3..a02dbf2d18 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 f4c8eac8f6..748d7ad296 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):
@@ -985,25 +989,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 6d4e75713d..45834777fc 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 3e640a846c..00b02fd19c 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 20d405af79..0000000000
--- 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 d00491fd7e..0000000000
--- 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 06c855ec94..0000000000
--- 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 e69de29bb2..0000000000
--- a/tests/qapi-schema/doc-optional.out
+++ /dev/null