[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 10/19] qapi: Clean up doc comment checking for implicit union bas
From: |
Markus Armbruster |
Subject: |
[PATCH 10/19] qapi: Clean up doc comment checking for implicit union base |
Date: |
Thu, 24 Oct 2019 13:02:28 +0200 |
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>
---
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
- [PATCH 00/19] qapi: Doc generation fixes, Markus Armbruster, 2019/10/24
- [PATCH 01/19] tests/qapi-schema: Demonstrate feature and enum doc comment bugs, Markus Armbruster, 2019/10/24
- [PATCH 13/19] qapi: Eliminate .check_doc() overrides, Markus Armbruster, 2019/10/24
- [PATCH 16/19] qapi: Fold normalize_enum() into check_enum(), Markus Armbruster, 2019/10/24
- [PATCH 12/19] qapi: Simplify ._make_implicit_object_type(), Markus Armbruster, 2019/10/24
- [PATCH 05/19] qemu-doc: Belatedly document QMP command deprecation, Markus Armbruster, 2019/10/24
- [PATCH 10/19] qapi: Clean up doc comment checking for implicit union base,
Markus Armbruster <=
- [PATCH 08/19] qapi: Split .connect_doc(), .check_doc() off .check(), Markus Armbruster, 2019/10/24
- [PATCH 18/19] qapi: Polish reporting of bogus member documentation, Markus Armbruster, 2019/10/24
- [PATCH 04/19] tests/qapi-schema: Fix feature documentation testing, Markus Armbruster, 2019/10/24
- [PATCH 03/19] tests/qapi-schema: Cover alternate documentation comments, Markus Armbruster, 2019/10/24
- [PATCH 09/19] qapi: Fix enum doc comment checking, Markus Armbruster, 2019/10/24
- [PATCH 07/19] qapi: De-duplicate entity documentation generation code, Markus Armbruster, 2019/10/24
- [PATCH 11/19] qapi: Fix doc comment checking for commands and events, Markus Armbruster, 2019/10/24
- [PATCH 15/19] qapi: Fold normalize_features() into check_features(), Markus Armbruster, 2019/10/24
- [PATCH 02/19] tests/qapi-schema: Demonstrate command and event doc comment bugs, Markus Armbruster, 2019/10/24
- [PATCH 19/19] qapi: Check feature documentation against the schema, Markus Armbruster, 2019/10/24