motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-12-11 16:00:50 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions

qapi: The #optional tag is redundant, drop

Browse source 
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>
This commit is contained in:
Markus Armbruster 2017-03-15 13:57:06 +01:00
parent aa964b7fdc
commit 1d8bda128d
18 changed files with 486 additions and 516 deletions
Download patch file Download diff file Expand all files Collapse all files

412
qapi/block-core.json
View file

File diff suppressed because it is too large Load diff

8
qapi/block.json
View file

@ -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.
#

22
qapi/crypto.json
View file

@ -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

10
qapi/event.json
View file

@ -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.
#

6
qapi/introspect.json
View file

@ -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

70
qapi/rocker.json
View file

@ -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

6
qapi/trace.json
View file

@ -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