From bf83f04e13063bb723fb8b9df789a3613c6d0ceb Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Thu, 24 Oct 2019 13:02:29 +0200 Subject: [PATCH] qapi: Fix doc comment checking for commands and events 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 Message-Id: <20191024110237.30963-12-armbru@redhat.com> --- 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 728990f4fb1..4c96137811a 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 c8c4bda153a..6f1c17f71f7 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 c16dce1fe0e..06e37c9c497 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 e69de29bb2d..e1101b16676 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 2c265d2ca33..bd143241ecd 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 4ccd7882530..e69de29bb2d 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 e69de29bb2d..114ff4a3c77 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 80d4e1240b1..23c83cc81f2 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 ad0367cd45c..e69de29bb2d 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.39.2