From 1d8bda128d2ff1f7e589c90d0ac468b95d260757 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Wed, 15 Mar 2017 13:57:06 +0100 Subject: 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 Reviewed-by: Eric Blake Message-Id: <1489582656-31133-18-git-send-email-armbru@redhat.com> --- docs/qapi-code-gen.txt | 12 +++++------- docs/writing-qmp-commands.txt | 4 ++-- 2 files changed, 7 insertions(+), 9 deletions(-) (limited to 'docs') 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 ## -- cgit v1.2.3