motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-07-27 12:23:53 -06: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

23
scripts/qapi.py
View file

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