aboutsummaryrefslogtreecommitdiff
path: root/scripts
diff options
context:
space:
mode:
authorMarkus Armbruster <armbru@redhat.com>2017-03-15 13:57:06 +0100
committerMarkus Armbruster <armbru@redhat.com>2017-03-16 07:13:02 +0100
commit1d8bda128d2ff1f7e589c90d0ac468b95d260757 (patch)
tree697f7ef26b1d5d4fb2fbfc9022e2c4122fe6e237 /scripts
parentaa964b7fdc2b9c6fd0dd530c44563b2a9d891d0f (diff)
downloadqemu-1d8bda128d2ff1f7e589c90d0ac468b95d260757.zip
qemu-1d8bda128d2ff1f7e589c90d0ac468b95d260757.tar.gz
qemu-1d8bda128d2ff1f7e589c90d0ac468b95d260757.tar.bz2
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>
Diffstat (limited to 'scripts')
-rw-r--r--scripts/qapi.py23
-rwxr-xr-xscripts/qapi2texi.py3
2 files changed, 5 insertions, 21 deletions
diff --git a/scripts/qapi.py b/scripts/qapi.py
index f4c8eac..748d7ad 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 6d4e757..4583477 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 ''