[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 11/19] qapi: Fix doc comment checking for commands and events
From: |
Markus Armbruster |
Subject: |
[PULL 11/19] qapi: Fix doc comment checking for commands and events |
Date: |
Tue, 29 Oct 2019 11:22:20 +0100 |
When a command's 'data' is an object, its doc comment describes the
arguments defined there. When 'data' names a type, the doc comment
does not describe arguments. Instead, the doc generator inserts a
pointer to the named type.
An event's doc comment works the same.
We don't actually check doc comments for commands and events.
Instead, QAPISchema._def_command() forwards the doc comment to the
implicit argument type, where it gets checked. Works because the
check only cares for the implicit argument type's members.
Not only is this needlessly hard to understand, it actually falls
apart in two cases:
* When 'data' is empty, there is nothing to forward to, and the doc
comment remains unchecked. Demonstrated by test doc-bad-event-arg.
* When 'data' names a type, we can't forward, as the type has its own
doc comment. The command or event's doc comment remains unchecked.
Demonstrated by test doc-bad-boxed-command-arg.
The forwarding goes back to commit 069fb5b250 "qapi: Prepare for
requiring more complete documentation", put to use in commit
816a57cd6e "qapi: Fix detection of bogus member documentation". That
fix was incomplete.
To fix this, make QAPISchemaCommand and QAPISchemaEvent check doc
comments, and drop the forwarding of doc comments to implicit argument
types.
Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>
---
qapi/net.json | 2 --
scripts/qapi/doc.py | 1 +
scripts/qapi/schema.py | 24 +++++++++++++++--
.../qapi-schema/doc-bad-boxed-command-arg.err | 1 +
.../doc-bad-boxed-command-arg.json | 1 -
.../qapi-schema/doc-bad-boxed-command-arg.out | 26 -------------------
tests/qapi-schema/doc-bad-event-arg.err | 1 +
tests/qapi-schema/doc-bad-event-arg.json | 1 -
tests/qapi-schema/doc-bad-event-arg.out | 19 --------------
9 files changed, 25 insertions(+), 51 deletions(-)
diff --git a/qapi/net.json b/qapi/net.json
index 728990f4fb..4c96137811 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -723,8 +723,6 @@
# Trigger generation of broadcast RARP frames to update network switches.
# This can be useful when network bonds fail-over the active slave.
#
-# @params: AnnounceParameters giving timing and repetition count of announce
-#
# Example:
#
# -> { "execute": "announce-self",
diff --git a/scripts/qapi/doc.py b/scripts/qapi/doc.py
index c8c4bda153..6f1c17f71f 100644
--- a/scripts/qapi/doc.py
+++ b/scripts/qapi/doc.py
@@ -185,6 +185,7 @@ def texi_members(doc, what, base=None, variants=None,
def texi_arguments(doc, boxed_arg_type):
if boxed_arg_type:
+ assert not doc.args
return ('\n@b{Arguments:} the members of @code{%s}\n'
% boxed_arg_type.name)
return texi_members(doc, 'Arguments')
diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py
index c16dce1fe0..06e37c9c49 100644
--- a/scripts/qapi/schema.py
+++ b/scripts/qapi/schema.py
@@ -739,6 +739,16 @@ class QAPISchemaCommand(QAPISchemaEntity):
for f in self.features:
f.check_clash(self.info, seen)
+ def connect_doc(self, doc=None):
+ doc = doc or self.doc
+ if doc:
+ if self.arg_type and self.arg_type.is_implicit():
+ self.arg_type.connect_doc(doc)
+
+ def check_doc(self):
+ if self.doc:
+ self.doc.check()
+
def visit(self, visitor):
QAPISchemaEntity.visit(self, visitor)
visitor.visit_command(self.name, self.info, self.ifcond,
@@ -775,6 +785,16 @@ class QAPISchemaEvent(QAPISchemaEntity):
"event's 'data' can take %s only with 'boxed': true"
% self.arg_type.describe())
+ def connect_doc(self, doc=None):
+ doc = doc or self.doc
+ if doc:
+ if self.arg_type and self.arg_type.is_implicit():
+ self.arg_type.connect_doc(doc)
+
+ def check_doc(self):
+ if self.doc:
+ self.doc.check()
+
def visit(self, visitor):
QAPISchemaEntity.visit(self, visitor)
visitor.visit_event(self.name, self.info, self.ifcond,
@@ -1026,7 +1046,7 @@ class QAPISchema(object):
features = expr.get('features', [])
if isinstance(data, OrderedDict):
data = self._make_implicit_object_type(
- name, info, doc, ifcond, 'arg', self._make_members(data, info))
+ name, info, None, ifcond, 'arg', self._make_members(data,
info))
if isinstance(rets, list):
assert len(rets) == 1
rets = self._make_array_type(rets[0], info)
@@ -1042,7 +1062,7 @@ class QAPISchema(object):
ifcond = expr.get('if')
if isinstance(data, OrderedDict):
data = self._make_implicit_object_type(
- name, info, doc, ifcond, 'arg', self._make_members(data, info))
+ name, info, None, ifcond, 'arg', self._make_members(data,
info))
self._def_entity(QAPISchemaEvent(name, info, doc, ifcond, data, boxed))
def _def_exprs(self, exprs):
diff --git a/tests/qapi-schema/doc-bad-boxed-command-arg.err
b/tests/qapi-schema/doc-bad-boxed-command-arg.err
index e69de29bb2..e1101b1667 100644
--- a/tests/qapi-schema/doc-bad-boxed-command-arg.err
+++ b/tests/qapi-schema/doc-bad-boxed-command-arg.err
@@ -0,0 +1 @@
+doc-bad-boxed-command-arg.json:9: the following documented members are not in
the declaration: a
diff --git a/tests/qapi-schema/doc-bad-boxed-command-arg.json
b/tests/qapi-schema/doc-bad-boxed-command-arg.json
index 2c265d2ca3..bd143241ec 100644
--- a/tests/qapi-schema/doc-bad-boxed-command-arg.json
+++ b/tests/qapi-schema/doc-bad-boxed-command-arg.json
@@ -1,5 +1,4 @@
# Boxed arguments are not to be documented with the command
-# BUG: not rejected
##
# @Args:
diff --git a/tests/qapi-schema/doc-bad-boxed-command-arg.out
b/tests/qapi-schema/doc-bad-boxed-command-arg.out
index 4ccd788253..e69de29bb2 100644
--- a/tests/qapi-schema/doc-bad-boxed-command-arg.out
+++ b/tests/qapi-schema/doc-bad-boxed-command-arg.out
@@ -1,26 +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-boxed-command-arg.json
-object Args
- member a: int optional=False
-command cmd-boxed Args -> None
- gen=True success_response=True boxed=True oob=False preconfig=False
-doc symbol=Args
- body=
-
- arg=a
-an argument
-doc symbol=cmd-boxed
- body=
-
- arg=a
-bogus
diff --git a/tests/qapi-schema/doc-bad-event-arg.err
b/tests/qapi-schema/doc-bad-event-arg.err
index e69de29bb2..114ff4a3c7 100644
--- a/tests/qapi-schema/doc-bad-event-arg.err
+++ b/tests/qapi-schema/doc-bad-event-arg.err
@@ -0,0 +1 @@
+doc-bad-event-arg.json:3: the following documented members are not in the
declaration: a
diff --git a/tests/qapi-schema/doc-bad-event-arg.json
b/tests/qapi-schema/doc-bad-event-arg.json
index 80d4e1240b..23c83cc81f 100644
--- a/tests/qapi-schema/doc-bad-event-arg.json
+++ b/tests/qapi-schema/doc-bad-event-arg.json
@@ -1,5 +1,4 @@
# Arguments 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-event-arg.out
b/tests/qapi-schema/doc-bad-event-arg.out
index ad0367cd45..e69de29bb2 100644
--- a/tests/qapi-schema/doc-bad-event-arg.out
+++ b/tests/qapi-schema/doc-bad-event-arg.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-event-arg.json
-event FOO None
- boxed=False
-doc symbol=FOO
- body=
-
- arg=a
-a
--
2.21.0
- [PULL 07/19] qapi: De-duplicate entity documentation generation code, (continued)
- [PULL 07/19] qapi: De-duplicate entity documentation generation code, Markus Armbruster, 2019/10/29
- [PULL 04/19] tests/qapi-schema: Fix feature documentation testing, Markus Armbruster, 2019/10/29
- [PULL 01/19] tests/qapi-schema: Demonstrate feature and enum doc comment bugs, Markus Armbruster, 2019/10/29
- [PULL 09/19] qapi: Fix enum doc comment checking, Markus Armbruster, 2019/10/29
- [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 <=
- [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, 2019/10/29
- [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