motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-07-27 20:33:54 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

qapi: Make doc comments optional where we don't need them

Browse source 
Since we added the documentation generator in commit 3313b61, doc
comments are mandatory.  That's a very good idea for a schema that
needs to be documented, but has proven to be annoying for testing.

Make doc comments optional again, but add a new directive

    { 'pragma': { 'doc-required': true } }

to let a QAPI schema require them.

Add test cases for the new pragma directive.  While there, plug a
minor hole in includ directive test coverage.

Require documentation in the schemas we actually want documented:
qapi-schema.json and qga/qapi-schema.json.

We could probably make qapi2texi.py cope with incomplete
documentation, but for now, simply make it refuse to run unless the
schema has 'doc-required': true.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <1489582656-31133-3-git-send-email-armbru@redhat.com>
[qapi-code-gen.txt wording tweaked]
Reviewed-by: Eric Blake <eblake@redhat.com>
This commit is contained in:
Markus Armbruster 2017-03-15 13:56:51 +01:00
parent e04dea8872
commit bc52d03ff5
26 changed files with 92 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

24
scripts/qapi.py
View file

@ -37,6 +37,9 @@ builtin_types = {
'QType': 'QTYPE_QSTRING',
}
# Are documentation comments required?
doc_required = False
# Whitelist of commands allowed to return a non-dictionary
returns_whitelist = [
# From QMP:
@ -277,6 +280,15 @@ class QAPISchemaParser(object):
"Value of 'include' must be a string")
self._include(include, info, os.path.dirname(abs_fname),
previously_included)
elif "pragma" in expr:
if len(expr) != 1:
raise QAPISemError(info, "Invalid 'pragma' directive")
pragma = expr['pragma']
if not isinstance(pragma, dict):
raise QAPISemError(
info, "Value of 'pragma' must be a dictionary")
for name, value in pragma.iteritems():
self._pragma(name, value, info)
else:
expr_elem = {'expr': expr,
'info': info}
@ -308,6 +320,16 @@ class QAPISchemaParser(object):
self.exprs.extend(exprs_include.exprs)
self.docs.extend(exprs_include.docs)
def _pragma(self, name, value, info):
global doc_required
if name == 'doc-required':
if not isinstance(value, bool):
raise QAPISemError(info,
"Pragma 'doc-required' must be boolean")
doc_required = value
else:
raise QAPISemError(info, "Unknown pragma '%s'" % name)
def accept(self, skip_comment=True):
while True:
self.tok = self.src[self.cursor]
@ -863,7 +885,7 @@ def check_exprs(exprs):
expr = expr_elem['expr']
info = expr_elem['info']
if 'doc' not in expr_elem:
if 'doc' not in expr_elem and doc_required:
raise QAPISemError(info,
"Expression missing documentation comment")