Commit 1d8bda12 authored by Markus Armbruster's avatar Markus Armbruster
Browse files

qapi: The #optional tag is redundant, drop 



We traditionally mark optional members #optional in the doc comment.
Before commit 3313b612, this was entirely manual.

Commit 3313b612 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: default avatarMarkus Armbruster <armbru@redhat.com>
Reviewed-by: default avatarEric Blake <eblake@redhat.com>
Message-Id: <1489582656-31133-18-git-send-email-armbru@redhat.com>
parent aa964b7f

docs/qapi-code-gen.txt

+5 −7
Original line number Diff line number Diff line
@@ -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.

docs/writing-qmp-commands.txt

+2 −2
Original line number Diff line number Diff line
@@ -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

##

qapi-schema.json

+188 −190

File changed.

Preview size limit exceeded, changes collapsed.

qapi/block-core.json

+206 −206

File changed.

Preview size limit exceeded, changes collapsed.

qapi/block.json

+4 −4
Original line number Diff line number Diff line
@@ -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.

#