From bf83f04e13063bb723fb8b9df789a3613c6d0ceb Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Thu, 24 Oct 2019 13:02:29 +0200 Subject: 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> --- scripts/qapi/doc.py | 1 + 1 file changed, 1 insertion(+) (limited to 'scripts/qapi/doc.py') 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') -- cgit v1.2.3