From bc52d03ff589a033843b4603cfdfd1518867c626 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Wed, 15 Mar 2017 13:56:51 +0100 Subject: qapi: Make doc comments optional where we don't need them 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 Message-Id: <1489582656-31133-3-git-send-email-armbru@redhat.com> [qapi-code-gen.txt wording tweaked] Reviewed-by: Eric Blake --- scripts/qapi.py | 24 +++++++++++++++++++++++- scripts/qapi2texi.py | 3 +++ 2 files changed, 26 insertions(+), 1 deletion(-) (limited to 'scripts') diff --git a/scripts/qapi.py b/scripts/qapi.py index 345cde157e..fe9d3cf36d 100644 --- a/scripts/qapi.py +++ b/scripts/qapi.py @@ -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") diff --git a/scripts/qapi2texi.py b/scripts/qapi2texi.py index 69f5edce4d..06d6abfa5a 100755 --- a/scripts/qapi2texi.py +++ b/scripts/qapi2texi.py @@ -254,6 +254,9 @@ def main(argv): sys.exit(1) schema = qapi.QAPISchema(argv[1]) + if not qapi.doc_required: + print >>sys.stderr, ("%s: need pragma 'doc-required' " + "to generate documentation" % argv[0]) print texi(schema.docs) -- cgit v1.2.3