From e151941d1b691402f7914750e025209b7839a1c0 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Thu, 24 Oct 2019 13:02:37 +0200 Subject: [PATCH] qapi: Check feature documentation against the schema Commit f3ed93d545 "qapi: Allow documentation for features" neglected to check documentation against the schema. Fix that: check them the same way we check arguments. Signed-off-by: Markus Armbruster Message-Id: <20191024110237.30963-20-armbru@redhat.com> --- scripts/qapi/parser.py | 31 ++++++++++++++++++++++--------- scripts/qapi/schema.py | 2 ++ tests/qapi-schema/doc-bad-feature.err | 1 + tests/qapi-schema/doc-bad-feature.json | 1 - tests/qapi-schema/doc-bad-feature.out | 19 ------------------- tests/qapi-schema/doc-undoc-feature.err | 2 ++ tests/qapi-schema/doc-undoc-feature.json | 1 - tests/qapi-schema/doc-undoc-feature.out | 21 --------------------- 8 files changed, 27 insertions(+), 51 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 6c45a00cf4..342792e410 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -555,18 +555,31 @@ class QAPIDoc(object): self.args[member.name] = QAPIDoc.ArgSection(member.name) self.args[member.name].connect(member) + def connect_feature(self, feature): + if feature.name not in self.features: + raise QAPISemError(feature.info, + "feature '%s' lacks documentation" + % feature.name) + self.features[feature.name] = QAPIDoc.ArgSection(feature.name) + self.features[feature.name].connect(feature) + def check_expr(self, expr): if self.has_section('Returns') and 'command' not in expr: raise QAPISemError(self.info, "'Returns:' is only valid for commands") def check(self): - bogus = [name for name, section in self.args.items() - if not section.member] - if bogus: - raise QAPISemError( - self.info, - "documented member%s '%s' %s not exist" - % ("s" if len(bogus) > 1 else "", - "', '".join(bogus), - "do" if len(bogus) > 1 else "does")) + + def check_args_section(args, info, what): + bogus = [name for name, section in args.items() + if not section.member] + if bogus: + raise QAPISemError( + self.info, + "documented member%s '%s' %s not exist" + % ("s" if len(bogus) > 1 else "", + "', '".join(bogus), + "do" if len(bogus) > 1 else "does")) + + check_args_section(self.args, self.info, 'members') + check_args_section(self.features, self.info, 'features') diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py index bdea9482fc..cf0045f34e 100644 --- a/scripts/qapi/schema.py +++ b/scripts/qapi/schema.py @@ -56,6 +56,8 @@ class QAPISchemaEntity(object): seen = {} for f in self.features: f.check_clash(self.info, seen) + if self.doc: + self.doc.connect_feature(f) self._checked = True diff --git a/tests/qapi-schema/doc-bad-feature.err b/tests/qapi-schema/doc-bad-feature.err index e69de29bb2..e4c62adfa3 100644 --- a/tests/qapi-schema/doc-bad-feature.err +++ b/tests/qapi-schema/doc-bad-feature.err @@ -0,0 +1 @@ +doc-bad-feature.json:3: documented member 'a' does not exist diff --git a/tests/qapi-schema/doc-bad-feature.json b/tests/qapi-schema/doc-bad-feature.json index 2a78e3b1db..3d49b8e607 100644 --- a/tests/qapi-schema/doc-bad-feature.json +++ b/tests/qapi-schema/doc-bad-feature.json @@ -1,5 +1,4 @@ # Features listed in the doc comment must exist in the actual schema -# BUG: nonexistent @a is not rejected ## # @foo: diff --git a/tests/qapi-schema/doc-bad-feature.out b/tests/qapi-schema/doc-bad-feature.out index fef4a3e400..e69de29bb2 100644 --- a/tests/qapi-schema/doc-bad-feature.out +++ b/tests/qapi-schema/doc-bad-feature.out @@ -1,19 +0,0 @@ -module None -object q_empty -enum QType - prefix QTYPE - member none - member qnull - member qnum - member qstring - member qdict - member qlist - member qbool -module doc-bad-feature.json -command foo None -> None - gen=True success_response=True boxed=False oob=False preconfig=False -doc symbol=foo - body= - - feature=a -a diff --git a/tests/qapi-schema/doc-undoc-feature.err b/tests/qapi-schema/doc-undoc-feature.err index e69de29bb2..62fc82d2b9 100644 --- a/tests/qapi-schema/doc-undoc-feature.err +++ b/tests/qapi-schema/doc-undoc-feature.err @@ -0,0 +1,2 @@ +doc-undoc-feature.json: In command 'foo': +doc-undoc-feature.json:9: feature 'undoc' lacks documentation diff --git a/tests/qapi-schema/doc-undoc-feature.json b/tests/qapi-schema/doc-undoc-feature.json index c7650d9974..c52f88e2cd 100644 --- a/tests/qapi-schema/doc-undoc-feature.json +++ b/tests/qapi-schema/doc-undoc-feature.json @@ -1,5 +1,4 @@ # Doc comment must cover all features -# BUG: missing documentation for @undoc not caught ## # @foo: diff --git a/tests/qapi-schema/doc-undoc-feature.out b/tests/qapi-schema/doc-undoc-feature.out index cdb097361f..e69de29bb2 100644 --- a/tests/qapi-schema/doc-undoc-feature.out +++ b/tests/qapi-schema/doc-undoc-feature.out @@ -1,21 +0,0 @@ -module None -object q_empty -enum QType - prefix QTYPE - member none - member qnull - member qnum - member qstring - member qdict - member qlist - member qbool -module doc-undoc-feature.json -command foo None -> None - gen=True success_response=True boxed=False oob=False preconfig=False - feature undoc - feature doc -doc symbol=foo - body= - - feature=doc -documented feature -- 2.11.4.GIT