[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 10/19] qapi: Clean up doc comment checking for implicit union base
From: |
Markus Armbruster |
Subject: |
[PULL 10/19] qapi: Clean up doc comment checking for implicit union base |
Date: |
Tue, 29 Oct 2019 11:22:19 +0100 |
An object type's doc comment describes the type's members, less the
ones defined in a named base type. Cases:
* Struct: the members are defined in 'data' and inherited from 'base'.
Since the base type cannot be implicit, the doc comment describes
just 'data'.
* Simple union: the only member is the implicit tag member @type, and
the doc comment describes it.
* Flat union with implicit base type: the members are defined in
'base', and the doc comment describes it.
* Flat union with named base type: the members are inherited from
'base'. The doc comment describes no members.
Before we can check a doc comment with .check_doc(), we need
.connect_doc() connect each of its "argument sections" to the member
it documents.
For structs and simple unions, this is straightforward: the members in
question are in .local_members, and .connect_doc() connects them.
For flat unions with a named base type, it's trivial: .local_members
is empty, and .connect_doc() does nothing.
For flat unions with an implicit base type, it's tricky. We have
QAPISchema._make_implicit_object_type() forward the union's doc
comment to the implicit base type, so that the base type's
.connect_doc() connects the members. The union's .connect_doc() does
nothing, as .local_members is empty.
Dirt effect: we check the doc comment twice, once for the union type,
and once for the implicit base type.
This is needlessly brittle and hard to understand. Clean up as
follows. Make the union's .connect_doc() connect an implicit base's
members itself. Do not forward the union's doc comment to its
implicit base type.
Requires extending .connect_doc() so it can work with a doc comment
other than self.doc. Add an optional argument for that.
Signed-off-by: Markus Armbruster <address@hidden>
Message-Id: <address@hidden>
---
scripts/qapi/schema.py | 27 ++++++++++++++++-----------
1 file changed, 16 insertions(+), 11 deletions(-)
diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py
index 0381e3cb40..c16dce1fe0 100644
--- a/scripts/qapi/schema.py
+++ b/scripts/qapi/schema.py
@@ -51,7 +51,7 @@ class QAPISchemaEntity(object):
os.path.dirname(schema.fname))
self._checked = True
- def connect_doc(self):
+ def connect_doc(self, doc=None):
pass
def check_doc(self):
@@ -224,10 +224,11 @@ class QAPISchemaEnumType(QAPISchemaType):
for m in self.members:
m.check_clash(self.info, seen)
- def connect_doc(self):
- if self.doc:
+ def connect_doc(self, doc=None):
+ doc = doc or self.doc
+ if doc:
for m in self.members:
- self.doc.connect_member(m)
+ doc.connect_member(m)
def check_doc(self):
if self.doc:
@@ -380,10 +381,13 @@ class QAPISchemaObjectType(QAPISchemaType):
for m in self.members:
m.check_clash(info, seen)
- def connect_doc(self):
- if self.doc:
+ def connect_doc(self, doc=None):
+ doc = doc or self.doc
+ if doc:
+ if self.base and self.base.is_implicit():
+ self.base.connect_doc(doc)
for m in self.local_members:
- self.doc.connect_member(m)
+ doc.connect_member(m)
def check_doc(self):
if self.doc:
@@ -657,10 +661,11 @@ class QAPISchemaAlternateType(QAPISchemaType):
% (v.describe(self.info), types_seen[qt]))
types_seen[qt] = v.name
- def connect_doc(self):
- if self.doc:
+ def connect_doc(self, doc=None):
+ doc = doc or self.doc
+ if doc:
for v in self.variants.variants:
- self.doc.connect_member(v)
+ doc.connect_member(v)
def check_doc(self):
if self.doc:
@@ -974,7 +979,7 @@ class QAPISchema(object):
tag_member = None
if isinstance(base, dict):
base = self._make_implicit_object_type(
- name, info, doc, ifcond,
+ name, info, None, ifcond,
'base', self._make_members(base, info))
if tag_name:
variants = [self._make_variant(key, value['type'],
--
2.21.0
- [PULL 00/19] QAPI patches for 2019-10-29, Markus Armbruster, 2019/10/29
- [PULL 12/19] qapi: Simplify ._make_implicit_object_type(), Markus Armbruster, 2019/10/29
- [PULL 03/19] tests/qapi-schema: Cover alternate documentation comments, Markus Armbruster, 2019/10/29
- [PULL 02/19] tests/qapi-schema: Demonstrate command and event doc comment bugs, Markus Armbruster, 2019/10/29
- [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 <=
- [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, 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