[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 19/19] qapi: Check feature documentation against the schema
From: |
Markus Armbruster |
Subject: |
[PULL 19/19] qapi: Check feature documentation against the schema |
Date: |
Tue, 29 Oct 2019 11:22:28 +0100 |
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 <address@hidden>
Message-Id: <address@hidden>
---
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.21.0
- [PULL 13/19] qapi: Eliminate .check_doc() overrides, (continued)
- [PULL 13/19] qapi: Eliminate .check_doc() overrides, Markus Armbruster, 2019/10/29
- [PULL 05/19] qemu-doc: Belatedly document QMP command deprecation, Markus Armbruster, 2019/10/29
- [PULL 10/19] qapi: Clean up doc comment checking for implicit union base, Markus Armbruster, 2019/10/29
- [PULL 14/19] qapi: Fold normalize_if() into check_if(), Markus Armbruster, 2019/10/29
- [PULL 06/19] qapi: Implement boxed event argument documentation, Markus Armbruster, 2019/10/29
- [PULL 15/19] qapi: Fold normalize_features() into check_features(), Markus Armbruster, 2019/10/29
- [PULL 11/19] qapi: Fix doc comment checking for commands and events, Markus Armbruster, 2019/10/29
- [PULL 16/19] qapi: Fold normalize_enum() into check_enum(), Markus Armbruster, 2019/10/29
- [PULL 18/19] qapi: Polish reporting of bogus member documentation, Markus Armbruster, 2019/10/29
- [PULL 17/19] qapi: Lift features into QAPISchemaEntity, Markus Armbruster, 2019/10/29
- [PULL 19/19] qapi: Check feature documentation against the schema,
Markus Armbruster <=
- [PULL 08/19] qapi: Split .connect_doc(), .check_doc() off .check(), Markus Armbruster, 2019/10/29
- Re: [PULL 00/19] QAPI patches for 2019-10-29, Peter Maydell, 2019/10/29