* [PULL 1/7] qapi: New QAPISchemaBranches, QAPISchemaAlternatives
2024-05-06 11:02 [PULL 0/7] QAPI patches patches for 2024-05-06 Markus Armbruster
@ 2024-05-06 11:02 ` Markus Armbruster
2024-05-06 11:02 ` [PATCH 1/7] qapi: make since sections special WIP Markus Armbruster
` (13 subsequent siblings)
14 siblings, 0 replies; 25+ messages in thread
From: Markus Armbruster @ 2024-05-06 11:02 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson
QAPISchemaVariants represents either a union type's branches, or an
alternate type's alternatives. Much of its code is conditional on
which one it actually is.
Create QAPISchemaBranches for branches, and QAPISchemaAlternatives for
alternatives, both subtypes of QAPISchemaVariants.
Replace QAPISchemaVariants by one of them where possible. Keep it
only where we actually deal with either of them.
QAPISchemaVariants.__init__() takes @tag_name and @tag_member, where
exactly one must be None: @tag_name for alternatives, @tag_member for
branches. Let QAPISchemaBranches.__init__() take just @tag_name, and
QAPISchemaAlternatives.__init__() take just @tag_member.
A later patch will move the conditional code to the subtypes.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
scripts/qapi/introspect.py | 7 ++++---
scripts/qapi/schema.py | 32 ++++++++++++++++++++++++--------
scripts/qapi/types.py | 6 ++++--
scripts/qapi/visit.py | 11 ++++++-----
4 files changed, 38 insertions(+), 18 deletions(-)
diff --git a/scripts/qapi/introspect.py b/scripts/qapi/introspect.py
index 4679b1bc2c..b866517942 100644
--- a/scripts/qapi/introspect.py
+++ b/scripts/qapi/introspect.py
@@ -26,6 +26,8 @@
from .gen import QAPISchemaMonolithicCVisitor
from .schema import (
QAPISchema,
+ QAPISchemaAlternatives,
+ QAPISchemaBranches,
QAPISchemaArrayType,
QAPISchemaBuiltinType,
QAPISchemaEntity,
@@ -36,7 +38,6 @@
QAPISchemaObjectTypeMember,
QAPISchemaType,
QAPISchemaVariant,
- QAPISchemaVariants,
)
from .source import QAPISourceInfo
@@ -335,7 +336,7 @@ def visit_object_type_flat(self, name: str, info: Optional[QAPISourceInfo],
ifcond: QAPISchemaIfCond,
features: List[QAPISchemaFeature],
members: List[QAPISchemaObjectTypeMember],
- variants: Optional[QAPISchemaVariants]) -> None:
+ variants: Optional[QAPISchemaBranches]) -> None:
obj: SchemaInfoObject = {
'members': [self._gen_object_member(m) for m in members]
}
@@ -347,7 +348,7 @@ def visit_object_type_flat(self, name: str, info: Optional[QAPISourceInfo],
def visit_alternate_type(self, name: str, info: Optional[QAPISourceInfo],
ifcond: QAPISchemaIfCond,
features: List[QAPISchemaFeature],
- variants: QAPISchemaVariants) -> None:
+ variants: QAPISchemaAlternatives) -> None:
self._gen_tree(
name, 'alternate',
{'members': [Annotated({'type': self._use_type(m.type)},
diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py
index 5924947fc3..5cdedfc2c8 100644
--- a/scripts/qapi/schema.py
+++ b/scripts/qapi/schema.py
@@ -215,7 +215,7 @@ def visit_object_type(
features: List[QAPISchemaFeature],
base: Optional[QAPISchemaObjectType],
members: List[QAPISchemaObjectTypeMember],
- variants: Optional[QAPISchemaVariants],
+ variants: Optional[QAPISchemaBranches],
) -> None:
pass
@@ -226,7 +226,7 @@ def visit_object_type_flat(
ifcond: QAPISchemaIfCond,
features: List[QAPISchemaFeature],
members: List[QAPISchemaObjectTypeMember],
- variants: Optional[QAPISchemaVariants],
+ variants: Optional[QAPISchemaBranches],
) -> None:
pass
@@ -236,7 +236,7 @@ def visit_alternate_type(
info: Optional[QAPISourceInfo],
ifcond: QAPISchemaIfCond,
features: List[QAPISchemaFeature],
- variants: QAPISchemaVariants,
+ variants: QAPISchemaAlternatives,
) -> None:
pass
@@ -524,7 +524,7 @@ def __init__(
features: Optional[List[QAPISchemaFeature]],
base: Optional[str],
local_members: List[QAPISchemaObjectTypeMember],
- variants: Optional[QAPISchemaVariants],
+ variants: Optional[QAPISchemaBranches],
):
# struct has local_members, optional base, and no variants
# union has base, variants, and no local_members
@@ -651,7 +651,7 @@ def __init__(
doc: Optional[QAPIDoc],
ifcond: Optional[QAPISchemaIfCond],
features: List[QAPISchemaFeature],
- variants: QAPISchemaVariants,
+ variants: QAPISchemaAlternatives,
):
super().__init__(name, info, doc, ifcond, features)
assert variants.tag_member
@@ -833,6 +833,22 @@ def check_clash(
v.type.check_clash(info, dict(seen))
+class QAPISchemaBranches(QAPISchemaVariants):
+ def __init__(self,
+ info: QAPISourceInfo,
+ variants: List[QAPISchemaVariant],
+ tag_name: str):
+ super().__init__(tag_name, info, None, variants)
+
+
+class QAPISchemaAlternatives(QAPISchemaVariants):
+ def __init__(self,
+ info: QAPISourceInfo,
+ variants: List[QAPISchemaVariant],
+ tag_member: QAPISchemaObjectTypeMember):
+ super().__init__(None, info, tag_member, variants)
+
+
class QAPISchemaMember:
""" Represents object members, enum members and features """
role = 'member'
@@ -1388,8 +1404,8 @@ def _def_union_type(self, expr: QAPIExpression) -> None:
self._def_definition(
QAPISchemaObjectType(name, info, expr.doc, ifcond, features,
base, members,
- QAPISchemaVariants(
- tag_name, info, None, variants)))
+ QAPISchemaBranches(
+ info, variants, tag_name)))
def _def_alternate_type(self, expr: QAPIExpression) -> None:
name = expr['alternate']
@@ -1407,7 +1423,7 @@ def _def_alternate_type(self, expr: QAPIExpression) -> None:
self._def_definition(
QAPISchemaAlternateType(
name, info, expr.doc, ifcond, features,
- QAPISchemaVariants(None, info, tag_member, variants)))
+ QAPISchemaAlternatives(info, variants, tag_member)))
def _def_command(self, expr: QAPIExpression) -> None:
name = expr['command']
diff --git a/scripts/qapi/types.py b/scripts/qapi/types.py
index c39d054d2c..23cdf3e83e 100644
--- a/scripts/qapi/types.py
+++ b/scripts/qapi/types.py
@@ -23,6 +23,8 @@
)
from .schema import (
QAPISchema,
+ QAPISchemaAlternatives,
+ QAPISchemaBranches,
QAPISchemaEnumMember,
QAPISchemaFeature,
QAPISchemaIfCond,
@@ -348,7 +350,7 @@ def visit_object_type(self,
features: List[QAPISchemaFeature],
base: Optional[QAPISchemaObjectType],
members: List[QAPISchemaObjectTypeMember],
- variants: Optional[QAPISchemaVariants]) -> None:
+ variants: Optional[QAPISchemaBranches]) -> None:
# Nothing to do for the special empty builtin
if name == 'q_empty':
return
@@ -369,7 +371,7 @@ def visit_alternate_type(self,
info: Optional[QAPISourceInfo],
ifcond: QAPISchemaIfCond,
features: List[QAPISchemaFeature],
- variants: QAPISchemaVariants) -> None:
+ variants: QAPISchemaAlternatives) -> None:
with ifcontext(ifcond, self._genh):
self._genh.preamble_add(gen_fwd_object_or_array(name))
self._genh.add(gen_object(name, ifcond, None,
diff --git a/scripts/qapi/visit.py b/scripts/qapi/visit.py
index a21b7b1468..990685498f 100644
--- a/scripts/qapi/visit.py
+++ b/scripts/qapi/visit.py
@@ -28,6 +28,8 @@
)
from .schema import (
QAPISchema,
+ QAPISchemaAlternatives,
+ QAPISchemaBranches,
QAPISchemaEnumMember,
QAPISchemaEnumType,
QAPISchemaFeature,
@@ -35,7 +37,6 @@
QAPISchemaObjectType,
QAPISchemaObjectTypeMember,
QAPISchemaType,
- QAPISchemaVariants,
)
from .source import QAPISourceInfo
@@ -63,7 +64,7 @@ def gen_visit_members_decl(name: str) -> str:
def gen_visit_object_members(name: str,
base: Optional[QAPISchemaObjectType],
members: List[QAPISchemaObjectTypeMember],
- variants: Optional[QAPISchemaVariants]) -> str:
+ variants: Optional[QAPISchemaBranches]) -> str:
ret = mcgen('''
bool visit_type_%(c_name)s_members(Visitor *v, %(c_name)s *obj, Error **errp)
@@ -222,7 +223,7 @@ def gen_visit_enum(name: str) -> str:
c_name=c_name(name))
-def gen_visit_alternate(name: str, variants: QAPISchemaVariants) -> str:
+def gen_visit_alternate(name: str, variants: QAPISchemaAlternatives) -> str:
ret = mcgen('''
bool visit_type_%(c_name)s(Visitor *v, const char *name,
@@ -393,7 +394,7 @@ def visit_object_type(self,
features: List[QAPISchemaFeature],
base: Optional[QAPISchemaObjectType],
members: List[QAPISchemaObjectTypeMember],
- variants: Optional[QAPISchemaVariants]) -> None:
+ variants: Optional[QAPISchemaBranches]) -> None:
# Nothing to do for the special empty builtin
if name == 'q_empty':
return
@@ -413,7 +414,7 @@ def visit_alternate_type(self,
info: Optional[QAPISourceInfo],
ifcond: QAPISchemaIfCond,
features: List[QAPISchemaFeature],
- variants: QAPISchemaVariants) -> None:
+ variants: QAPISchemaAlternatives) -> None:
with ifcontext(ifcond, self._genh, self._genc):
self._genh.add(gen_visit_decl(name))
self._genc.add(gen_visit_alternate(name, variants))
--
2.44.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH 1/7] qapi: make since sections special WIP
2024-05-06 11:02 [PULL 0/7] QAPI patches patches for 2024-05-06 Markus Armbruster
2024-05-06 11:02 ` [PULL 1/7] qapi: New QAPISchemaBranches, QAPISchemaAlternatives Markus Armbruster
@ 2024-05-06 11:02 ` Markus Armbruster
2024-05-06 11:44 ` Philippe Mathieu-Daudé
2024-05-06 12:45 ` Markus Armbruster
2024-05-06 11:02 ` [PULL 2/7] qapi: Rename visitor parameter @variants to @branches Markus Armbruster
` (12 subsequent siblings)
14 siblings, 2 replies; 25+ messages in thread
From: Markus Armbruster @ 2024-05-06 11:02 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson
since moves to end in generated output
---
docs/sphinx/qapidoc.py | 22 +++++++++++++++++-----
scripts/qapi/parser.py | 5 +++--
tests/qapi-schema/test-qapi.py | 2 ++
3 files changed, 22 insertions(+), 7 deletions(-)
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 8d428c64b0..ac81003f0e 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -250,6 +250,13 @@ def _nodes_for_features(self, doc):
section += dlnode
return [section]
+ def _nodes_for_since(self, doc):
+ if doc.since:
+ section = self._make_section('Since')
+ self._parse_text_into_node(doc.since.text, section)
+ return [section]
+ return []
+
def _nodes_for_example(self, exampletext):
"""Return list of doctree nodes for a code example snippet"""
return [nodes.literal_block(exampletext, exampletext)]
@@ -305,7 +312,8 @@ def visit_enum_type(self, name, info, ifcond, features, members, prefix):
self._nodes_for_enum_values(doc)
+ self._nodes_for_features(doc)
+ self._nodes_for_sections(doc)
- + self._nodes_for_if_section(ifcond))
+ + self._nodes_for_if_section(ifcond)
+ + self._nodes_for_since(doc))
def visit_object_type(self, name, info, ifcond, features,
base, members, variants):
@@ -316,7 +324,8 @@ def visit_object_type(self, name, info, ifcond, features,
self._nodes_for_members(doc, 'Members', base, variants)
+ self._nodes_for_features(doc)
+ self._nodes_for_sections(doc)
- + self._nodes_for_if_section(ifcond))
+ + self._nodes_for_if_section(ifcond)
+ + self._nodes_for_since(doc))
def visit_alternate_type(self, name, info, ifcond, features, variants):
doc = self._cur_doc
@@ -324,7 +333,8 @@ def visit_alternate_type(self, name, info, ifcond, features, variants):
self._nodes_for_members(doc, 'Members')
+ self._nodes_for_features(doc)
+ self._nodes_for_sections(doc)
- + self._nodes_for_if_section(ifcond))
+ + self._nodes_for_if_section(ifcond)
+ + self._nodes_for_since(doc))
def visit_command(self, name, info, ifcond, features, arg_type,
ret_type, gen, success_response, boxed, allow_oob,
@@ -335,7 +345,8 @@ def visit_command(self, name, info, ifcond, features, arg_type,
arg_type if boxed else None)
+ self._nodes_for_features(doc)
+ self._nodes_for_sections(doc)
- + self._nodes_for_if_section(ifcond))
+ + self._nodes_for_if_section(ifcond)
+ + self._nodes_for_since(doc))
def visit_event(self, name, info, ifcond, features, arg_type, boxed):
doc = self._cur_doc
@@ -344,7 +355,8 @@ def visit_event(self, name, info, ifcond, features, arg_type, boxed):
arg_type if boxed else None)
+ self._nodes_for_features(doc)
+ self._nodes_for_sections(doc)
- + self._nodes_for_if_section(ifcond))
+ + self._nodes_for_if_section(ifcond)
+ + self._nodes_for_since(doc))
def symbol(self, doc, entity):
"""Add documentation for one symbol to the document tree
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 7b13a583ac..0237d13da9 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -646,7 +646,7 @@ def __init__(self, info: QAPISourceInfo, symbol: Optional[str] = None):
self.errors: Optional[QAPIDoc.Section] = None
# "Since" section
self.since: Optional[QAPIDoc.Section] = None
- # sections other than .body, .args, .features
+ # sections other than .body, .args, .features, .since
self.sections: List[QAPIDoc.Section] = []
def end(self) -> None:
@@ -683,7 +683,8 @@ def new_tagged_section(self, info: QAPISourceInfo, tag: str) -> None:
raise QAPISemError(
info, "duplicated '%s' section" % tag)
self.since = section
- self.sections.append(section)
+ if tag != 'Since':
+ self.sections.append(section)
self.all_sections.append(section)
def _new_description(self, info: QAPISourceInfo, name: str,
diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py
index 40095431ae..642daa29a4 100755
--- a/tests/qapi-schema/test-qapi.py
+++ b/tests/qapi-schema/test-qapi.py
@@ -131,6 +131,8 @@ def test_frontend(fname):
print(' feature=%s\n%s' % (feat, section.text))
for section in doc.sections:
print(' section=%s\n%s' % (section.tag, section.text))
+ if doc.since:
+ print(' section=%s\n%s' % (doc.since.tag, doc.since.text))
def open_test_result(dir_name, file_name, update):
--
2.44.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PULL 2/7] qapi: Rename visitor parameter @variants to @branches
2024-05-06 11:02 [PULL 0/7] QAPI patches patches for 2024-05-06 Markus Armbruster
2024-05-06 11:02 ` [PULL 1/7] qapi: New QAPISchemaBranches, QAPISchemaAlternatives Markus Armbruster
2024-05-06 11:02 ` [PATCH 1/7] qapi: make since sections special WIP Markus Armbruster
@ 2024-05-06 11:02 ` Markus Armbruster
2024-05-06 11:02 ` [PATCH 2/7] sphinx/qapidoc: Tweak "Since" section formatting WIP Markus Armbruster
` (11 subsequent siblings)
14 siblings, 0 replies; 25+ messages in thread
From: Markus Armbruster @ 2024-05-06 11:02 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson
The previous commit narrowed the type of .visit_object_type()
parameter @variants from QAPISchemaVariants to QAPISchemaBranches.
Rename it to @branches.
Same for .visit_object_type_flat().
A few of these pass @branches to helper functions:
QAPISchemaGenRSTVisitor.visit_object_type() to ._nodes_for_members()
and ._nodes_for_variant_when(), and
QAPISchemaGenVisitVisitor.visit_object_type() to
gen_visit_object_members(). Rename the helpers' @variants parameters
to @branches as well.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
docs/sphinx/qapidoc.py | 18 +++++++++---------
scripts/qapi/introspect.py | 8 ++++----
scripts/qapi/schema.py | 4 ++--
scripts/qapi/types.py | 4 ++--
scripts/qapi/visit.py | 12 ++++++------
tests/qapi-schema/test-qapi.py | 4 ++--
6 files changed, 25 insertions(+), 25 deletions(-)
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 8d428c64b0..71362ba929 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -145,22 +145,22 @@ def _nodes_for_one_member(self, member):
term.extend(self._nodes_for_ifcond(member.ifcond))
return term
- def _nodes_for_variant_when(self, variants, variant):
+ def _nodes_for_variant_when(self, branches, variant):
"""Return list of Text, literal nodes for variant 'when' clause
Return a list of doctree nodes which give text like
'when tagname is variant (If: ...)' suitable for use in
- the 'variants' part of a definition list.
+ the 'branches' part of a definition list.
"""
term = [nodes.Text(' when '),
- nodes.literal('', variants.tag_member.name),
+ nodes.literal('', branches.tag_member.name),
nodes.Text(' is '),
nodes.literal('', '"%s"' % variant.name)]
if variant.ifcond.is_present():
term.extend(self._nodes_for_ifcond(variant.ifcond))
return term
- def _nodes_for_members(self, doc, what, base=None, variants=None):
+ def _nodes_for_members(self, doc, what, base=None, branches=None):
"""Return list of doctree nodes for the table of members"""
dlnode = nodes.definition_list()
for section in doc.args.values():
@@ -178,14 +178,14 @@ def _nodes_for_members(self, doc, what, base=None, variants=None):
nodes.literal('', base.doc_type())],
None)
- if variants:
- for v in variants.variants:
+ if branches:
+ for v in branches.variants:
if v.type.name == 'q_empty':
continue
assert not v.type.is_implicit()
term = [nodes.Text('The members of '),
nodes.literal('', v.type.doc_type())]
- term.extend(self._nodes_for_variant_when(variants, v))
+ term.extend(self._nodes_for_variant_when(branches, v))
dlnode += self._make_dlitem(term, None)
if not dlnode.children:
@@ -308,12 +308,12 @@ def visit_enum_type(self, name, info, ifcond, features, members, prefix):
+ self._nodes_for_if_section(ifcond))
def visit_object_type(self, name, info, ifcond, features,
- base, members, variants):
+ base, members, branches):
doc = self._cur_doc
if base and base.is_implicit():
base = None
self._add_doc('Object',
- self._nodes_for_members(doc, 'Members', base, variants)
+ self._nodes_for_members(doc, 'Members', base, branches)
+ self._nodes_for_features(doc)
+ self._nodes_for_sections(doc)
+ self._nodes_for_if_section(ifcond))
diff --git a/scripts/qapi/introspect.py b/scripts/qapi/introspect.py
index b866517942..7852591490 100644
--- a/scripts/qapi/introspect.py
+++ b/scripts/qapi/introspect.py
@@ -336,13 +336,13 @@ def visit_object_type_flat(self, name: str, info: Optional[QAPISourceInfo],
ifcond: QAPISchemaIfCond,
features: List[QAPISchemaFeature],
members: List[QAPISchemaObjectTypeMember],
- variants: Optional[QAPISchemaBranches]) -> None:
+ branches: Optional[QAPISchemaBranches]) -> None:
obj: SchemaInfoObject = {
'members': [self._gen_object_member(m) for m in members]
}
- if variants:
- obj['tag'] = variants.tag_member.name
- obj['variants'] = [self._gen_variant(v) for v in variants.variants]
+ if branches:
+ obj['tag'] = branches.tag_member.name
+ obj['variants'] = [self._gen_variant(v) for v in branches.variants]
self._gen_tree(name, 'object', obj, ifcond, features)
def visit_alternate_type(self, name: str, info: Optional[QAPISourceInfo],
diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py
index 5cdedfc2c8..65c82dd4f1 100644
--- a/scripts/qapi/schema.py
+++ b/scripts/qapi/schema.py
@@ -215,7 +215,7 @@ def visit_object_type(
features: List[QAPISchemaFeature],
base: Optional[QAPISchemaObjectType],
members: List[QAPISchemaObjectTypeMember],
- variants: Optional[QAPISchemaBranches],
+ branches: Optional[QAPISchemaBranches],
) -> None:
pass
@@ -226,7 +226,7 @@ def visit_object_type_flat(
ifcond: QAPISchemaIfCond,
features: List[QAPISchemaFeature],
members: List[QAPISchemaObjectTypeMember],
- variants: Optional[QAPISchemaBranches],
+ branches: Optional[QAPISchemaBranches],
) -> None:
pass
diff --git a/scripts/qapi/types.py b/scripts/qapi/types.py
index 23cdf3e83e..0abb78f3a8 100644
--- a/scripts/qapi/types.py
+++ b/scripts/qapi/types.py
@@ -350,13 +350,13 @@ def visit_object_type(self,
features: List[QAPISchemaFeature],
base: Optional[QAPISchemaObjectType],
members: List[QAPISchemaObjectTypeMember],
- variants: Optional[QAPISchemaBranches]) -> None:
+ branches: Optional[QAPISchemaBranches]) -> None:
# Nothing to do for the special empty builtin
if name == 'q_empty':
return
with ifcontext(ifcond, self._genh):
self._genh.preamble_add(gen_fwd_object_or_array(name))
- self._genh.add(gen_object(name, ifcond, base, members, variants))
+ self._genh.add(gen_object(name, ifcond, base, members, branches))
with ifcontext(ifcond, self._genh, self._genc):
if base and not base.is_implicit():
self._genh.add(gen_upcast(name, base))
diff --git a/scripts/qapi/visit.py b/scripts/qapi/visit.py
index 990685498f..fbae5f3e4e 100644
--- a/scripts/qapi/visit.py
+++ b/scripts/qapi/visit.py
@@ -64,7 +64,7 @@ def gen_visit_members_decl(name: str) -> str:
def gen_visit_object_members(name: str,
base: Optional[QAPISchemaObjectType],
members: List[QAPISchemaObjectTypeMember],
- variants: Optional[QAPISchemaBranches]) -> str:
+ branches: Optional[QAPISchemaBranches]) -> str:
ret = mcgen('''
bool visit_type_%(c_name)s_members(Visitor *v, %(c_name)s *obj, Error **errp)
@@ -132,8 +132,8 @@ def gen_visit_object_members(name: str,
''')
ret += memb.ifcond.gen_endif()
- if variants:
- tag_member = variants.tag_member
+ if branches:
+ tag_member = branches.tag_member
assert isinstance(tag_member.type, QAPISchemaEnumType)
ret += mcgen('''
@@ -141,7 +141,7 @@ def gen_visit_object_members(name: str,
''',
c_name=c_name(tag_member.name))
- for var in variants.variants:
+ for var in branches.variants:
case_str = c_enum_const(tag_member.type.name, var.name,
tag_member.type.prefix)
ret += var.ifcond.gen_if()
@@ -394,14 +394,14 @@ def visit_object_type(self,
features: List[QAPISchemaFeature],
base: Optional[QAPISchemaObjectType],
members: List[QAPISchemaObjectTypeMember],
- variants: Optional[QAPISchemaBranches]) -> None:
+ branches: Optional[QAPISchemaBranches]) -> None:
# Nothing to do for the special empty builtin
if name == 'q_empty':
return
with ifcontext(ifcond, self._genh, self._genc):
self._genh.add(gen_visit_members_decl(name))
self._genc.add(gen_visit_object_members(name, base,
- members, variants))
+ members, branches))
# TODO Worth changing the visitor signature, so we could
# directly use rather than repeat type.is_implicit()?
if not name.startswith('q_'):
diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py
index 40095431ae..7c67ad8d9b 100755
--- a/tests/qapi-schema/test-qapi.py
+++ b/tests/qapi-schema/test-qapi.py
@@ -48,7 +48,7 @@ def visit_array_type(self, name, info, ifcond, element_type):
self._print_if(ifcond)
def visit_object_type(self, name, info, ifcond, features,
- base, members, variants):
+ base, members, branches):
print('object %s' % name)
if base:
print(' base %s' % base.name)
@@ -57,7 +57,7 @@ def visit_object_type(self, name, info, ifcond, features,
% (m.name, m.type.name, m.optional))
self._print_if(m.ifcond, 8)
self._print_features(m.features, indent=8)
- self._print_variants(variants)
+ self._print_variants(branches)
self._print_if(ifcond)
self._print_features(features)
--
2.44.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH 2/7] sphinx/qapidoc: Tweak "Since" section formatting WIP
2024-05-06 11:02 [PULL 0/7] QAPI patches patches for 2024-05-06 Markus Armbruster
` (2 preceding siblings ...)
2024-05-06 11:02 ` [PULL 2/7] qapi: Rename visitor parameter @variants to @branches Markus Armbruster
@ 2024-05-06 11:02 ` Markus Armbruster
2024-05-06 12:45 ` Markus Armbruster
2024-05-06 11:02 ` [PULL 3/7] qapi: Rename visitor parameter @variants to @alternatives Markus Armbruster
` (10 subsequent siblings)
14 siblings, 1 reply; 25+ messages in thread
From: Markus Armbruster @ 2024-05-06 11:02 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson
---
docs/sphinx/qapidoc.py | 6 +++---
tests/qapi-schema/doc-good.txt | 6 +-----
2 files changed, 4 insertions(+), 8 deletions(-)
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index ac81003f0e..f19f5ded78 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -252,9 +252,9 @@ def _nodes_for_features(self, doc):
def _nodes_for_since(self, doc):
if doc.since:
- section = self._make_section('Since')
- self._parse_text_into_node(doc.since.text, section)
- return [section]
+ # TODO emphasis
+ return [nodes.paragraph(
+ '', '', nodes.Text('Since: ' + doc.since.text))]
return []
def _nodes_for_example(self, exampletext):
diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt
index 847db70412..56d50d4992 100644
--- a/tests/qapi-schema/doc-good.txt
+++ b/tests/qapi-schema/doc-good.txt
@@ -235,11 +235,7 @@ Examples
- *verbatim*
- {braces}
-
-Since
-~~~~~
-
-2.10
+Since: 2.10
"cmd-boxed" (Command)
--
2.44.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PULL 3/7] qapi: Rename visitor parameter @variants to @alternatives
2024-05-06 11:02 [PULL 0/7] QAPI patches patches for 2024-05-06 Markus Armbruster
` (3 preceding siblings ...)
2024-05-06 11:02 ` [PATCH 2/7] sphinx/qapidoc: Tweak "Since" section formatting WIP Markus Armbruster
@ 2024-05-06 11:02 ` Markus Armbruster
2024-05-06 11:02 ` [PATCH 3/7] qapi: make returns sections special WIP Markus Armbruster
` (9 subsequent siblings)
14 siblings, 0 replies; 25+ messages in thread
From: Markus Armbruster @ 2024-05-06 11:02 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson
A previous commit narrowed the type of .visit_alternate_type()
parameter @variants from QAPISchemaVariants to QAPISchemaAlternatives.
Rename it to @alternatives.
One of them passes @alternatives to helper function
gen_visit_alternate(). Rename its @variants parameter to
@alternatives as well.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
docs/sphinx/qapidoc.py | 3 ++-
scripts/qapi/introspect.py | 4 ++--
scripts/qapi/schema.py | 2 +-
scripts/qapi/types.py | 4 ++--
scripts/qapi/visit.py | 9 +++++----
tests/qapi-schema/test-qapi.py | 5 +++--
6 files changed, 15 insertions(+), 12 deletions(-)
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 71362ba929..f270b494f0 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -318,7 +318,8 @@ def visit_object_type(self, name, info, ifcond, features,
+ self._nodes_for_sections(doc)
+ self._nodes_for_if_section(ifcond))
- def visit_alternate_type(self, name, info, ifcond, features, variants):
+ def visit_alternate_type(self, name, info, ifcond, features,
+ alternatives):
doc = self._cur_doc
self._add_doc('Alternate',
self._nodes_for_members(doc, 'Members')
diff --git a/scripts/qapi/introspect.py b/scripts/qapi/introspect.py
index 7852591490..86c075a6ad 100644
--- a/scripts/qapi/introspect.py
+++ b/scripts/qapi/introspect.py
@@ -348,12 +348,12 @@ def visit_object_type_flat(self, name: str, info: Optional[QAPISourceInfo],
def visit_alternate_type(self, name: str, info: Optional[QAPISourceInfo],
ifcond: QAPISchemaIfCond,
features: List[QAPISchemaFeature],
- variants: QAPISchemaAlternatives) -> None:
+ alternatives: QAPISchemaAlternatives) -> None:
self._gen_tree(
name, 'alternate',
{'members': [Annotated({'type': self._use_type(m.type)},
m.ifcond)
- for m in variants.variants]},
+ for m in alternatives.variants]},
ifcond, features
)
diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py
index 65c82dd4f1..2b67992aee 100644
--- a/scripts/qapi/schema.py
+++ b/scripts/qapi/schema.py
@@ -236,7 +236,7 @@ def visit_alternate_type(
info: Optional[QAPISourceInfo],
ifcond: QAPISchemaIfCond,
features: List[QAPISchemaFeature],
- variants: QAPISchemaAlternatives,
+ alternatives: QAPISchemaAlternatives,
) -> None:
pass
diff --git a/scripts/qapi/types.py b/scripts/qapi/types.py
index 0abb78f3a8..69f5f6ffd0 100644
--- a/scripts/qapi/types.py
+++ b/scripts/qapi/types.py
@@ -371,11 +371,11 @@ def visit_alternate_type(self,
info: Optional[QAPISourceInfo],
ifcond: QAPISchemaIfCond,
features: List[QAPISchemaFeature],
- variants: QAPISchemaAlternatives) -> None:
+ alternatives: QAPISchemaAlternatives) -> None:
with ifcontext(ifcond, self._genh):
self._genh.preamble_add(gen_fwd_object_or_array(name))
self._genh.add(gen_object(name, ifcond, None,
- [variants.tag_member], variants))
+ [alternatives.tag_member], alternatives))
with ifcontext(ifcond, self._genh, self._genc):
self._gen_type_cleanup(name)
diff --git a/scripts/qapi/visit.py b/scripts/qapi/visit.py
index fbae5f3e4e..e766acaac9 100644
--- a/scripts/qapi/visit.py
+++ b/scripts/qapi/visit.py
@@ -223,7 +223,8 @@ def gen_visit_enum(name: str) -> str:
c_name=c_name(name))
-def gen_visit_alternate(name: str, variants: QAPISchemaAlternatives) -> str:
+def gen_visit_alternate(name: str,
+ alternatives: QAPISchemaAlternatives) -> str:
ret = mcgen('''
bool visit_type_%(c_name)s(Visitor *v, const char *name,
@@ -245,7 +246,7 @@ def gen_visit_alternate(name: str, variants: QAPISchemaAlternatives) -> str:
''',
c_name=c_name(name))
- for var in variants.variants:
+ for var in alternatives.variants:
ret += var.ifcond.gen_if()
ret += mcgen('''
case %(case)s:
@@ -414,10 +415,10 @@ def visit_alternate_type(self,
info: Optional[QAPISourceInfo],
ifcond: QAPISchemaIfCond,
features: List[QAPISchemaFeature],
- variants: QAPISchemaAlternatives) -> None:
+ alternatives: QAPISchemaAlternatives) -> None:
with ifcontext(ifcond, self._genh, self._genc):
self._genh.add(gen_visit_decl(name))
- self._genc.add(gen_visit_alternate(name, variants))
+ self._genc.add(gen_visit_alternate(name, alternatives))
def gen_visit(schema: QAPISchema,
diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py
index 7c67ad8d9b..7e3f9f4aa1 100755
--- a/tests/qapi-schema/test-qapi.py
+++ b/tests/qapi-schema/test-qapi.py
@@ -61,9 +61,10 @@ def visit_object_type(self, name, info, ifcond, features,
self._print_if(ifcond)
self._print_features(features)
- def visit_alternate_type(self, name, info, ifcond, features, variants):
+ def visit_alternate_type(self, name, info, ifcond, features,
+ alternatives):
print('alternate %s' % name)
- self._print_variants(variants)
+ self._print_variants(alternatives)
self._print_if(ifcond)
self._print_features(features)
--
2.44.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH 3/7] qapi: make returns sections special WIP
2024-05-06 11:02 [PULL 0/7] QAPI patches patches for 2024-05-06 Markus Armbruster
` (4 preceding siblings ...)
2024-05-06 11:02 ` [PULL 3/7] qapi: Rename visitor parameter @variants to @alternatives Markus Armbruster
@ 2024-05-06 11:02 ` Markus Armbruster
2024-05-06 12:46 ` Markus Armbruster
2024-05-06 11:02 ` [PULL 4/7] qapi: Rename QAPISchemaObjectType.variants to .branches Markus Armbruster
` (8 subsequent siblings)
14 siblings, 1 reply; 25+ messages in thread
From: Markus Armbruster @ 2024-05-06 11:02 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson
returns moves in generated output
---
docs/sphinx/qapidoc.py | 8 ++++++++
scripts/qapi/parser.py | 4 ++--
tests/qapi-schema/doc-good.out | 4 ++--
tests/qapi-schema/doc-good.txt | 12 ++++++------
tests/qapi-schema/test-qapi.py | 2 ++
5 files changed, 20 insertions(+), 10 deletions(-)
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index f19f5ded78..24bf1d9a90 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -250,6 +250,13 @@ def _nodes_for_features(self, doc):
section += dlnode
return [section]
+ def _nodes_for_returns(self, doc, ret_type):
+ if doc.returns:
+ section = self._make_section('Returns')
+ self._parse_text_into_node(doc.returns.text, section)
+ return [section]
+ return []
+
def _nodes_for_since(self, doc):
if doc.since:
# TODO emphasis
@@ -343,6 +350,7 @@ def visit_command(self, name, info, ifcond, features, arg_type,
self._add_doc('Command',
self._nodes_for_arguments(doc,
arg_type if boxed else None)
+ + self._nodes_for_returns(doc, ret_type)
+ self._nodes_for_features(doc)
+ self._nodes_for_sections(doc)
+ self._nodes_for_if_section(ifcond)
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 0237d13da9..e8a482c37d 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -646,7 +646,7 @@ def __init__(self, info: QAPISourceInfo, symbol: Optional[str] = None):
self.errors: Optional[QAPIDoc.Section] = None
# "Since" section
self.since: Optional[QAPIDoc.Section] = None
- # sections other than .body, .args, .features, .since
+ # sections other than .body, .args, .features, .returns, .since
self.sections: List[QAPIDoc.Section] = []
def end(self) -> None:
@@ -683,7 +683,7 @@ def new_tagged_section(self, info: QAPISourceInfo, tag: str) -> None:
raise QAPISemError(
info, "duplicated '%s' section" % tag)
self.since = section
- if tag != 'Since':
+ if tag not in ('Returns', 'Since'):
self.sections.append(section)
self.all_sections.append(section)
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index 716a9a4102..f2be711a2c 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -165,14 +165,14 @@ description starts on the same line
remainder indented differently
arg=arg3
+ section=Returns
+@Object
feature=cmd-feat1
a feature
feature=cmd-feat2
another feature
section=Note
@arg3 is undocumented
- section=Returns
-@Object
section=Errors
some
section=TODO
diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt
index 56d50d4992..fd88301431 100644
--- a/tests/qapi-schema/doc-good.txt
+++ b/tests/qapi-schema/doc-good.txt
@@ -184,6 +184,12 @@ Arguments
Not documented
+Returns
+~~~~~~~
+
+"Object"
+
+
Features
~~~~~~~~
@@ -200,12 +206,6 @@ Note
"arg3" is undocumented
-Returns
-~~~~~~~
-
-"Object"
-
-
Errors
~~~~~~
diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py
index 642daa29a4..1628efe0f3 100755
--- a/tests/qapi-schema/test-qapi.py
+++ b/tests/qapi-schema/test-qapi.py
@@ -127,6 +127,8 @@ def test_frontend(fname):
print(' body=\n%s' % doc.body.text)
for arg, section in doc.args.items():
print(' arg=%s\n%s' % (arg, section.text))
+ if doc.returns:
+ print(' section=%s\n%s' % (doc.returns.tag, doc.returns.text))
for feat, section in doc.features.items():
print(' feature=%s\n%s' % (feat, section.text))
for section in doc.sections:
--
2.44.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PULL 4/7] qapi: Rename QAPISchemaObjectType.variants to .branches
2024-05-06 11:02 [PULL 0/7] QAPI patches patches for 2024-05-06 Markus Armbruster
` (5 preceding siblings ...)
2024-05-06 11:02 ` [PATCH 3/7] qapi: make returns sections special WIP Markus Armbruster
@ 2024-05-06 11:02 ` Markus Armbruster
2024-05-06 11:02 ` [PATCH 4/7] qapidoc: Generate default Returns WIP Markus Armbruster
` (7 subsequent siblings)
14 siblings, 0 replies; 25+ messages in thread
From: Markus Armbruster @ 2024-05-06 11:02 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson
A previous commit narrowed the type of QAPISchemaObjectType.variants
from QAPISchemaVariants to QAPISchemaBranches. Rename it to
.branches.
Same for .__init__() parameter @variants.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
scripts/qapi/commands.py | 2 +-
scripts/qapi/events.py | 2 +-
scripts/qapi/gen.py | 2 +-
scripts/qapi/schema.py | 36 ++++++++++++++++++------------------
scripts/qapi/types.py | 2 +-
5 files changed, 22 insertions(+), 22 deletions(-)
diff --git a/scripts/qapi/commands.py b/scripts/qapi/commands.py
index d1fdf4182c..79951a841f 100644
--- a/scripts/qapi/commands.py
+++ b/scripts/qapi/commands.py
@@ -64,7 +64,7 @@ def gen_call(name: str,
assert arg_type
argstr = '&arg, '
elif arg_type:
- assert not arg_type.variants
+ assert not arg_type.branches
for memb in arg_type.members:
assert not memb.ifcond.is_present()
if memb.need_has():
diff --git a/scripts/qapi/events.py b/scripts/qapi/events.py
index 3cf01e96b6..d1f639981a 100644
--- a/scripts/qapi/events.py
+++ b/scripts/qapi/events.py
@@ -51,7 +51,7 @@ def gen_param_var(typ: QAPISchemaObjectType) -> str:
Initialize it with the function arguments defined in `gen_event_send`.
"""
- assert not typ.variants
+ assert not typ.branches
ret = mcgen('''
%(c_name)s param = {
''',
diff --git a/scripts/qapi/gen.py b/scripts/qapi/gen.py
index 5412716617..6a8abe0041 100644
--- a/scripts/qapi/gen.py
+++ b/scripts/qapi/gen.py
@@ -118,7 +118,7 @@ def build_params(arg_type: Optional[QAPISchemaObjectType],
ret += '%s arg' % arg_type.c_param_type()
sep = ', '
elif arg_type:
- assert not arg_type.variants
+ assert not arg_type.branches
for memb in arg_type.members:
assert not memb.ifcond.is_present()
ret += sep
diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py
index 2b67992aee..c9ff794d0c 100644
--- a/scripts/qapi/schema.py
+++ b/scripts/qapi/schema.py
@@ -524,20 +524,20 @@ def __init__(
features: Optional[List[QAPISchemaFeature]],
base: Optional[str],
local_members: List[QAPISchemaObjectTypeMember],
- variants: Optional[QAPISchemaBranches],
+ branches: Optional[QAPISchemaBranches],
):
- # struct has local_members, optional base, and no variants
- # union has base, variants, and no local_members
+ # struct has local_members, optional base, and no branches
+ # union has base, branches, and no local_members
super().__init__(name, info, doc, ifcond, features)
- self.meta = 'union' if variants else 'struct'
+ self.meta = 'union' if branches else 'struct'
for m in local_members:
m.set_defined_in(name)
- if variants is not None:
- variants.set_defined_in(name)
+ if branches is not None:
+ branches.set_defined_in(name)
self._base_name = base
self.base = None
self.local_members = local_members
- self.variants = variants
+ self.branches = branches
self.members: List[QAPISchemaObjectTypeMember]
self._check_complete = False
@@ -561,7 +561,7 @@ def check(self, schema: QAPISchema) -> None:
self.base = schema.resolve_type(self._base_name, self.info,
"'base'")
if (not isinstance(self.base, QAPISchemaObjectType)
- or self.base.variants):
+ or self.base.branches):
raise QAPISemError(
self.info,
"'base' requires a struct type, %s isn't"
@@ -577,9 +577,9 @@ def check(self, schema: QAPISchema) -> None:
# Cast down to the subtype.
members = cast(List[QAPISchemaObjectTypeMember], list(seen.values()))
- if self.variants:
- self.variants.check(schema, seen)
- self.variants.check_clash(self.info, seen)
+ if self.branches:
+ self.branches.check(schema, seen)
+ self.branches.check_clash(self.info, seen)
self.members = members
self._check_complete = True # mark completed
@@ -595,8 +595,8 @@ def check_clash(
assert self._checked
for m in self.members:
m.check_clash(info, seen)
- if self.variants:
- self.variants.check_clash(info, seen)
+ if self.branches:
+ self.branches.check_clash(info, seen)
def connect_doc(self, doc: Optional[QAPIDoc] = None) -> None:
super().connect_doc(doc)
@@ -612,7 +612,7 @@ def is_implicit(self) -> bool:
return self.name.startswith('q_')
def is_empty(self) -> bool:
- return not self.members and not self.variants
+ return not self.members and not self.branches
def has_conditional_members(self) -> bool:
return any(m.ifcond.is_present() for m in self.members)
@@ -635,10 +635,10 @@ def visit(self, visitor: QAPISchemaVisitor) -> None:
super().visit(visitor)
visitor.visit_object_type(
self.name, self.info, self.ifcond, self.features,
- self.base, self.local_members, self.variants)
+ self.base, self.local_members, self.branches)
visitor.visit_object_type_flat(
self.name, self.info, self.ifcond, self.features,
- self.members, self.variants)
+ self.members, self.branches)
class QAPISchemaAlternateType(QAPISchemaType):
@@ -1035,7 +1035,7 @@ def check(self, schema: QAPISchema) -> None:
"command's 'data' cannot take %s"
% arg_type.describe())
self.arg_type = arg_type
- if self.arg_type.variants and not self.boxed:
+ if self.arg_type.branches and not self.boxed:
raise QAPISemError(
self.info,
"command's 'data' can take %s only with 'boxed': true"
@@ -1103,7 +1103,7 @@ def check(self, schema: QAPISchema) -> None:
"event's 'data' cannot take %s"
% typ.describe())
self.arg_type = typ
- if self.arg_type.variants and not self.boxed:
+ if self.arg_type.branches and not self.boxed:
raise QAPISemError(
self.info,
"event's 'data' can take %s only with 'boxed': true"
diff --git a/scripts/qapi/types.py b/scripts/qapi/types.py
index 69f5f6ffd0..0dd0b00ada 100644
--- a/scripts/qapi/types.py
+++ b/scripts/qapi/types.py
@@ -171,7 +171,7 @@ def gen_object(name: str, ifcond: QAPISchemaIfCond,
if not isinstance(obj, QAPISchemaObjectType):
continue
ret += gen_object(obj.name, obj.ifcond, obj.base,
- obj.local_members, obj.variants)
+ obj.local_members, obj.branches)
ret += mcgen('''
--
2.44.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH 4/7] qapidoc: Generate default Returns WIP
2024-05-06 11:02 [PULL 0/7] QAPI patches patches for 2024-05-06 Markus Armbruster
` (6 preceding siblings ...)
2024-05-06 11:02 ` [PULL 4/7] qapi: Rename QAPISchemaObjectType.variants to .branches Markus Armbruster
@ 2024-05-06 11:02 ` Markus Armbruster
2024-05-06 12:46 ` Markus Armbruster
2024-05-06 11:02 ` [PATCH 5/7] qapi: Drop "Returns" section where default is fine WIP Markus Armbruster
` (6 subsequent siblings)
14 siblings, 1 reply; 25+ messages in thread
From: Markus Armbruster @ 2024-05-06 11:02 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson
Affected:
x-debug-query-block-graph
query-tpm
query-dirty-rate
query-vcpu-dirty-limit
query-vm-generation-id
query-memory-size-summary
query-memory-devices
query-acpi-ospm-status
query-stats-schemas
---
docs/sphinx/qapidoc.py | 9 +++++++--
1 file changed, 7 insertions(+), 2 deletions(-)
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 24bf1d9a90..35627ca741 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -251,9 +251,14 @@ def _nodes_for_features(self, doc):
return [section]
def _nodes_for_returns(self, doc, ret_type):
- if doc.returns:
+ assert not doc.returns or ret_type
+ if ret_type:
section = self._make_section('Returns')
- self._parse_text_into_node(doc.returns.text, section)
+ if doc.returns:
+ self._parse_text_into_node(doc.returns.text, section)
+ else:
+ section += nodes.paragraph(
+ '', '', nodes.Text(ret_type.doc_type()))
return [section]
return []
--
2.44.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH 5/7] qapi: Drop "Returns" section where default is fine WIP
2024-05-06 11:02 [PULL 0/7] QAPI patches patches for 2024-05-06 Markus Armbruster
` (7 preceding siblings ...)
2024-05-06 11:02 ` [PATCH 4/7] qapidoc: Generate default Returns WIP Markus Armbruster
@ 2024-05-06 11:02 ` Markus Armbruster
2024-05-06 12:46 ` Markus Armbruster
2024-05-06 11:02 ` [PULL 5/7] qapi: Rename QAPISchemaAlternateType.variants to .alternatives Markus Armbruster
` (5 subsequent siblings)
14 siblings, 1 reply; 25+ messages in thread
From: Markus Armbruster @ 2024-05-06 11:02 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson
---
qapi/audio.json | 2 --
qapi/block-core.json | 21 ++++-----------------
qapi/block-export.json | 2 +-
qapi/block.json | 3 ---
qapi/char.json | 10 +---------
qapi/control.json | 5 -----
qapi/cryptodev.json | 2 --
qapi/dump.json | 5 -----
qapi/job.json | 2 --
qapi/machine-target.json | 6 ++----
qapi/machine.json | 36 ------------------------------------
qapi/migration.json | 12 ------------
qapi/misc-target.json | 16 ----------------
qapi/misc.json | 16 ++--------------
qapi/pci.json | 2 +-
qapi/qdev.json | 3 ---
qapi/qom.json | 8 --------
qapi/replay.json | 2 --
qapi/rocker.json | 8 --------
qapi/run-state.json | 2 --
qapi/stats.json | 2 +-
qapi/tpm.json | 4 ----
qapi/trace.json | 5 ++---
qapi/ui.json | 10 ----------
qapi/virtio.json | 10 ----------
qapi/yank.json | 2 --
26 files changed, 14 insertions(+), 182 deletions(-)
diff --git a/qapi/audio.json b/qapi/audio.json
index 519697c0cd..bf11ca6d0a 100644
--- a/qapi/audio.json
+++ b/qapi/audio.json
@@ -515,8 +515,6 @@
#
# Returns information about audiodev configuration
#
-# Returns: array of @Audiodev
-#
# Since: 8.0
##
{ 'command': 'query-audiodevs',
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 746d1694c2..fab1a45365 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -757,10 +757,8 @@
##
# @query-block:
#
-# Get a list of BlockInfo for all virtual block devices.
-#
-# Returns: a list of @BlockInfo describing each virtual block device.
-# Filter nodes that were created implicitly are skipped over.
+# Get a list of BlockInfo for all virtual block devices. Filter nodes
+# that were created implicitly are skipped over.
#
# Since: 0.14
#
@@ -1164,8 +1162,6 @@
# that were created implicitly are skipped over in this mode.
# (Since 2.3)
#
-# Returns: A list of @BlockStats for each virtual block devices.
-#
# Since: 0.14
#
# Example:
@@ -1434,9 +1430,8 @@
##
# @query-block-jobs:
#
-# Return information about long-running block device operations.
-#
-# Returns: a list of @BlockJobInfo for each active block job
+# Return information about active, long-running block device
+# operations ("block jobs").
#
# Since: 1.1
##
@@ -1941,8 +1936,6 @@
# @flat: Omit the nested data about backing image ("backing-image"
# key) if true. Default is false (Since 5.0)
#
-# Returns: the list of BlockDeviceInfo
-#
# Since: 2.0
#
# Example:
@@ -2456,9 +2449,6 @@
#
# @unstable: This command is meant for debugging.
#
-# Returns:
-# BlockDirtyBitmapSha256
-#
# Errors:
# - If @node is not a valid block device, DeviceNotFound
# - If @name is not found or if hashing has failed, GenericError
@@ -6100,9 +6090,6 @@
#
# @name: optional the snapshot's name to be deleted
#
-# Returns:
-# SnapshotInfo
-#
# Errors:
# - If @device is not a valid block device, GenericError
# - If snapshot not found, GenericError
diff --git a/qapi/block-export.json b/qapi/block-export.json
index 3919a2d5b9..89a277db80 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -464,7 +464,7 @@
##
# @query-block-exports:
#
-# Returns: A list of BlockExportInfo describing all block exports
+# Query block export information.
#
# Since: 5.2
##
diff --git a/qapi/block.json b/qapi/block.json
index 5de99fe09d..97e2ccc4f1 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -86,9 +86,6 @@
# Returns a list of information about each persistent reservation
# manager.
#
-# Returns: a list of @PRManagerInfo for each persistent reservation
-# manager
-#
# Since: 3.0
##
{ 'command': 'query-pr-managers', 'returns': ['PRManagerInfo'],
diff --git a/qapi/char.json b/qapi/char.json
index 777dde55d9..87e1523946 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -36,8 +36,6 @@
#
# Returns information about current character devices.
#
-# Returns: a list of @ChardevInfo
-#
# Since: 0.14
#
# Example:
@@ -82,8 +80,6 @@
#
# Returns information about character device backends.
#
-# Returns: a list of @ChardevBackendInfo
-#
# Since: 2.0
#
# Example:
@@ -173,7 +169,7 @@
# - The return value is always Unicode regardless of format, like
# any other string.
#
-# Returns: data read from the device
+# Returns: data read from the device (string)
#
# Since: 1.4
#
@@ -695,8 +691,6 @@
#
# @backend: backend type and parameters
#
-# Returns: ChardevReturn.
-#
# Since: 1.4
#
# Examples:
@@ -731,8 +725,6 @@
#
# @backend: new backend type and parameters
#
-# Returns: ChardevReturn.
-#
# Since: 2.10
#
# Examples:
diff --git a/qapi/control.json b/qapi/control.json
index 6bdbf077c2..39510430fc 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -93,9 +93,6 @@
#
# Returns the current version of QEMU.
#
-# Returns: A @VersionInfo object describing the current version of
-# QEMU.
-#
# Since: 0.14
#
# Example:
@@ -131,8 +128,6 @@
#
# Return a list of supported QMP commands by this server
#
-# Returns: A list of @CommandInfo for all supported commands
-#
# Since: 0.14
#
# Example:
diff --git a/qapi/cryptodev.json b/qapi/cryptodev.json
index 68289f4984..6707aa506f 100644
--- a/qapi/cryptodev.json
+++ b/qapi/cryptodev.json
@@ -89,8 +89,6 @@
#
# Returns information about current crypto devices.
#
-# Returns: a list of @QCryptodevInfo
-#
# Since: 8.0
##
{ 'command': 'query-cryptodev', 'returns': ['QCryptodevInfo']}
diff --git a/qapi/dump.json b/qapi/dump.json
index 2fa9504d86..ec18387c71 100644
--- a/qapi/dump.json
+++ b/qapi/dump.json
@@ -146,8 +146,6 @@
#
# Query latest dump status.
#
-# Returns: A @DumpStatus object showing the dump status.
-#
# Since: 2.6
#
# Example:
@@ -197,9 +195,6 @@
#
# Returns the available formats for dump-guest-memory
#
-# Returns: A @DumpGuestMemoryCapability object listing available
-# formats for dump-guest-memory
-#
# Since: 2.0
#
# Example:
diff --git a/qapi/job.json b/qapi/job.json
index b3957207a4..4f22edde56 100644
--- a/qapi/job.json
+++ b/qapi/job.json
@@ -269,8 +269,6 @@
#
# Return information about jobs.
#
-# Returns: a list with a @JobInfo for each active job
-#
# Since: 3.0
##
{ 'command': 'query-jobs', 'returns': ['JobInfo'] }
diff --git a/qapi/machine-target.json b/qapi/machine-target.json
index 29e695aa06..4ef7ef7b43 100644
--- a/qapi/machine-target.json
+++ b/qapi/machine-target.json
@@ -380,8 +380,6 @@
#
# Return a list of supported virtual CPU definitions
#
-# Returns: a list of CpuDefinitionInfo
-#
# Since: 1.2
##
{ 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'],
@@ -499,12 +497,12 @@
##
# @query-s390x-cpu-polarization:
#
+# Return the machine's CPU polarization.
+#
# Features:
#
# @unstable: This command is experimental.
#
-# Returns: the machine's CPU polarization
-#
# Since: 8.2
##
{ 'command': 'query-s390x-cpu-polarization', 'returns': 'CpuPolarizationInfo',
diff --git a/qapi/machine.json b/qapi/machine.json
index bce6e1bbc4..b8f4c83914 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -100,8 +100,6 @@
#
# Returns information about all virtual CPUs.
#
-# Returns: list of @CpuInfoFast
-#
# Since: 2.12
#
# Example:
@@ -217,8 +215,6 @@
#
# @unstable: Argument @compat-props is experimental.
#
-# Returns: a list of MachineInfo
-#
# Since: 1.2
#
# Example:
@@ -267,8 +263,6 @@
#
# Return information on the current virtual machine.
#
-# Returns: CurrentMachineParams
-#
# Since: 4.0
##
{ 'command': 'query-current-machine', 'returns': 'CurrentMachineParams' }
@@ -290,8 +284,6 @@
#
# Return information about the target for this QEMU
#
-# Returns: TargetInfo
-#
# Since: 1.2
##
{ 'command': 'query-target', 'returns': 'TargetInfo' }
@@ -315,8 +307,6 @@
#
# Query the guest UUID information.
#
-# Returns: The @UuidInfo for the guest
-#
# Since: 0.14
#
# Example:
@@ -468,8 +458,6 @@
#
# Returns information about KVM acceleration
#
-# Returns: @KvmInfo
-#
# Since: 0.14
#
# Example:
@@ -924,8 +912,6 @@
#
# Returns information for all memory backends.
#
-# Returns: a list of @Memdev.
-#
# Since: 2.1
#
# Example:
@@ -1042,8 +1028,6 @@
#
# TODO: Better documentation; currently there is none.
#
-# Returns: a list of HotpluggableCPU objects.
-#
# Since: 2.7
#
# Examples:
@@ -1155,9 +1139,6 @@
#
# Return information about the balloon device.
#
-# Returns:
-# @BalloonInfo
-#
# Errors:
# - If the balloon driver is enabled but not functional because
# the KVM kernel module cannot support it, KVMMissingCap
@@ -1221,9 +1202,6 @@
# Returns the hv-balloon driver data contained in the last received
# "STATUS" message from the guest.
#
-# Returns:
-# @HvBalloonInfo
-#
# Errors:
# - If no hv-balloon device is present, guest memory status
# reporting is not enabled or no guest memory status report
@@ -1729,8 +1707,6 @@
#
# @unstable: This command is meant for debugging.
#
-# Returns: interrupt statistics
-#
# Since: 6.2
##
{ 'command': 'x-query-irq',
@@ -1746,8 +1722,6 @@
#
# @unstable: This command is meant for debugging.
#
-# Returns: TCG compiler statistics
-#
# Since: 6.2
##
{ 'command': 'x-query-jit',
@@ -1764,8 +1738,6 @@
#
# @unstable: This command is meant for debugging.
#
-# Returns: topology information
-#
# Since: 6.2
##
{ 'command': 'x-query-numa',
@@ -1781,8 +1753,6 @@
#
# @unstable: This command is meant for debugging.
#
-# Returns: TCG opcode counters
-#
# Since: 6.2
##
{ 'command': 'x-query-opcount',
@@ -1799,8 +1769,6 @@
#
# @unstable: This command is meant for debugging.
#
-# Returns: system ramblock information
-#
# Since: 6.2
##
{ 'command': 'x-query-ramblock',
@@ -1816,8 +1784,6 @@
#
# @unstable: This command is meant for debugging.
#
-# Returns: registered ROMs
-#
# Since: 6.2
##
{ 'command': 'x-query-roms',
@@ -1833,8 +1799,6 @@
#
# @unstable: This command is meant for debugging.
#
-# Returns: USB device information
-#
# Since: 6.2
##
{ 'command': 'x-query-usb',
diff --git a/qapi/migration.json b/qapi/migration.json
index 8c65b90328..e22645253c 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -305,8 +305,6 @@
# status and if block migration is active another one with block
# migration status.
#
-# Returns: @MigrationInfo
-#
# Since: 0.14
#
# Examples:
@@ -597,8 +595,6 @@
#
# Returns information about the current migration capabilities status
#
-# Returns: @MigrationCapabilityStatus
-#
# Since: 1.2
#
# Example:
@@ -1412,8 +1408,6 @@
#
# Returns information about the current migration parameters
#
-# Returns: @MigrationParameters
-#
# Since: 2.4
#
# Example:
@@ -1997,8 +1991,6 @@
#
# Query replication status while the vm is running.
#
-# Returns: A @ReplicationStatus object showing the status.
-#
# Example:
#
# -> { "execute": "query-xen-replication-status" }
@@ -2051,8 +2043,6 @@
#
# Query COLO status while the vm is running.
#
-# Returns: A @COLOStatus object showing the status.
-#
# Example:
#
# -> { "execute": "query-colo-status" }
@@ -2419,8 +2409,6 @@
#
# Returns information of migration threads
#
-# Returns: @MigrationThreadInfo
-#
# Since: 7.2
##
{ 'command': 'query-migrationthreads',
diff --git a/qapi/misc-target.json b/qapi/misc-target.json
index 4e0a6492a9..9edb7c1ade 100644
--- a/qapi/misc-target.json
+++ b/qapi/misc-target.json
@@ -85,8 +85,6 @@
#
# Returns information about SEV
#
-# Returns: @SevInfo
-#
# Since: 2.12
#
# Example:
@@ -116,8 +114,6 @@
#
# Query the SEV guest launch information.
#
-# Returns: The @SevLaunchMeasureInfo for the guest
-#
# Since: 2.12
#
# Example:
@@ -161,8 +157,6 @@
# This command is used to get the SEV capabilities, and is supported
# on AMD X86 platforms only.
#
-# Returns: SevCapability objects.
-#
# Since: 2.12
#
# Example:
@@ -215,8 +209,6 @@
# @mnonce: a random 16 bytes value encoded in base64 (it will be
# included in report)
#
-# Returns: SevAttestationReport objects.
-#
# Since: 6.1
#
# Example:
@@ -280,8 +272,6 @@
# This command is ARM-only. It will return a list of GICCapability
# objects that describe its capability bits.
#
-# Returns: a list of GICCapability objects.
-#
# Since: 2.6
#
# Example:
@@ -338,8 +328,6 @@
#
# Returns information about SGX
#
-# Returns: @SGXInfo
-#
# Since: 6.2
#
# Example:
@@ -357,8 +345,6 @@
#
# Returns information from host SGX capabilities
#
-# Returns: @SGXInfo
-#
# Since: 6.2
#
# Example:
@@ -432,8 +418,6 @@
#
# Query the Xen event channels opened by the guest.
#
-# Returns: list of open event channel ports.
-#
# Since: 8.0
#
# Example:
diff --git a/qapi/misc.json b/qapi/misc.json
index ec30e5c570..ab2d234973 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -56,8 +56,6 @@
#
# Return the name information of a guest.
#
-# Returns: @NameInfo of the guest
-#
# Since: 0.14
#
# Example:
@@ -101,14 +99,12 @@
##
# @query-iothreads:
#
-# Returns a list of information about each iothread.
+# Returns information about each iothread.
#
# Note: this list excludes the QEMU main loop thread, which is not
# declared using the -object iothread command-line option. It is
# always the main thread of the process.
#
-# Returns: a list of @IOThreadInfo for each iothread
-#
# Since: 2.0
#
# Example:
@@ -331,9 +327,6 @@
#
# @opaque: A free-form string that can be used to describe the fd.
#
-# Returns:
-# @AddfdInfo
-#
# Errors:
# - If file descriptor was not received, GenericError
# - If @fdset-id is a negative value, GenericError
@@ -415,8 +408,6 @@
#
# Return information describing all fd sets.
#
-# Returns: A list of @FdsetInfo
-#
# Since: 1.2
#
# Note: The list of fd sets is shared by all monitor connections.
@@ -514,10 +505,7 @@
#
# Query command line option schema.
#
-# @option: option name
-#
-# Returns: list of @CommandLineOptionInfo for all options (or for the
-# given @option).
+# @option: limit query to just @option
#
# Errors:
# - if the given @option doesn't exist
diff --git a/qapi/pci.json b/qapi/pci.json
index 08bf695863..6355411373 100644
--- a/qapi/pci.json
+++ b/qapi/pci.json
@@ -178,7 +178,7 @@
# Returns: a list of @PciInfo for each PCI bus. Each bus is
# represented by a json-object, which has a key with a json-array
# of all PCI devices attached to it. Each device is represented
-# by a json-object.
+# by a json-object. TODO check
#
# Since: 0.14
#
diff --git a/qapi/qdev.json b/qapi/qdev.json
index facaa0bc6a..798dc831d5 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -17,9 +17,6 @@
#
# @typename: the type name of a device
#
-# Returns: a list of ObjectPropertyInfo describing a devices
-# properties
-#
# Note: objects can create properties at runtime, for example to
# describe links between different devices and/or objects. These
# properties are not included in the output of this command.
diff --git a/qapi/qom.json b/qapi/qom.json
index 38dde6d785..d1dc216474 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -54,9 +54,6 @@
# @path: the path within the object model. See @qom-get for a
# description of this parameter.
#
-# Returns: a list of @ObjectPropertyInfo that describe the properties
-# of the object.
-#
# Since: 1.2
#
# Example:
@@ -178,9 +175,6 @@
#
# @abstract: if true, include abstract types in the results
#
-# Returns: a list of @ObjectTypeInfo or an empty list if no results
-# are found
-#
# Since: 1.1
##
{ 'command': 'qom-list-types',
@@ -199,8 +193,6 @@
# describe links between different devices and/or objects. These
# properties are not included in the output of this command.
#
-# Returns: a list of ObjectPropertyInfo describing object properties
-#
# Since: 2.12
##
{ 'command': 'qom-list-properties',
diff --git a/qapi/replay.json b/qapi/replay.json
index d3559f9c8f..e66823bf03 100644
--- a/qapi/replay.json
+++ b/qapi/replay.json
@@ -50,8 +50,6 @@
# instruction count which may be used for @replay-break and
# @replay-seek commands.
#
-# Returns: record/replay information.
-#
# Since: 5.2
#
# Example:
diff --git a/qapi/rocker.json b/qapi/rocker.json
index 5635cf174f..03c42713b4 100644
--- a/qapi/rocker.json
+++ b/qapi/rocker.json
@@ -26,8 +26,6 @@
#
# Return rocker switch information.
#
-# Returns: @Rocker information
-#
# Since: 2.4
#
# Example:
@@ -94,8 +92,6 @@
#
# Return rocker switch port information.
#
-# Returns: a list of @RockerPort information
-#
# Since: 2.4
#
# Example:
@@ -236,8 +232,6 @@
# @tbl-id: flow table ID. If tbl-id is not specified, returns flow
# information for all tables.
#
-# Returns: rocker OF-DPA flow information
-#
# Since: 2.4
#
# Example:
@@ -311,8 +305,6 @@
# @type: group type. If type is not specified, returns group
# information for all group types.
#
-# Returns: rocker OF-DPA group information
-#
# Since: 2.4
#
# Example:
diff --git a/qapi/run-state.json b/qapi/run-state.json
index f8773f23b2..37c30ee3a2 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -119,8 +119,6 @@
#
# Query the run status of the VM
#
-# Returns: @StatusInfo reflecting the VM
-#
# Since: 0.14
#
# Example:
diff --git a/qapi/stats.json b/qapi/stats.json
index 578b52c7ef..0753c11aa2 100644
--- a/qapi/stats.json
+++ b/qapi/stats.json
@@ -187,7 +187,7 @@
# to return statistics about.
#
# Returns: a list of StatsResult, one for each provider and object
-# (e.g., for each vCPU).
+# (e.g., for each vCPU). TODO check
#
# Since: 7.1
##
diff --git a/qapi/tpm.json b/qapi/tpm.json
index 1577b5c259..6002a17f0e 100644
--- a/qapi/tpm.json
+++ b/qapi/tpm.json
@@ -27,8 +27,6 @@
#
# Return a list of supported TPM models
#
-# Returns: a list of TpmModel
-#
# Since: 1.5
#
# Example:
@@ -58,8 +56,6 @@
#
# Return a list of supported TPM types
#
-# Returns: a list of TpmType
-#
# Since: 1.5
#
# Example:
diff --git a/qapi/trace.json b/qapi/trace.json
index 043d12f83e..27a98fc9d9 100644
--- a/qapi/trace.json
+++ b/qapi/trace.json
@@ -52,7 +52,8 @@
#
# Query the state of events.
#
-# @name: Event name pattern (case-sensitive glob).
+# @name: Limit the query to events with a name matching @name
+# (case-sensitive glob).
#
# @vcpu: The vCPU to query (since 2.7).
#
@@ -60,8 +61,6 @@
#
# @deprecated: Member @vcpu is deprecated, and always ignored.
#
-# Returns: a list of @TraceEventInfo for the matching events
-#
# Since: 2.2
#
# Example:
diff --git a/qapi/ui.json b/qapi/ui.json
index f610bce118..2b7f0b8401 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -327,8 +327,6 @@
#
# Returns information about the current SPICE server
#
-# Returns: @SpiceInfo
-#
# Since: 0.14
#
# Example:
@@ -658,8 +656,6 @@
#
# Returns information about the current VNC server
#
-# Returns: @VncInfo
-#
# Since: 0.14
#
# Example:
@@ -689,8 +685,6 @@
#
# Returns a list of vnc servers. The list can be empty.
#
-# Returns: a list of @VncInfo2
-#
# Since: 2.3
##
{ 'command': 'query-vnc-servers', 'returns': ['VncInfo2'],
@@ -824,8 +818,6 @@
#
# Returns information about each active mouse device
#
-# Returns: a list of @MouseInfo for each device
-#
# Since: 0.14
#
# Example:
@@ -1564,8 +1556,6 @@
#
# Returns information about display configuration
#
-# Returns: @DisplayOptions
-#
# Since: 3.1
##
{ 'command': 'query-display-options',
diff --git a/qapi/virtio.json b/qapi/virtio.json
index 74fc27c702..476a2a4192 100644
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -30,8 +30,6 @@
#
# @unstable: This command is meant for debugging.
#
-# Returns: List of gathered VirtIODevices
-#
# Since: 7.2
#
# Example:
@@ -199,8 +197,6 @@
#
# @unstable: This command is meant for debugging.
#
-# Returns: VirtioStatus of the virtio device
-#
# Since: 7.2
#
# Examples:
@@ -557,8 +553,6 @@
#
# @unstable: This command is meant for debugging.
#
-# Returns: VirtQueueStatus of the VirtQueue
-#
# Notes: last_avail_idx will not be displayed in the case where the
# selected VirtIODevice has a running vhost device and the
# VirtIODevice VirtQueue index (queue) does not exist for the
@@ -686,8 +680,6 @@
#
# @unstable: This command is meant for debugging.
#
-# Returns: VirtVhostQueueStatus of the vhost_virtqueue
-#
# Since: 7.2
#
# Examples:
@@ -835,8 +827,6 @@
#
# @unstable: This command is meant for debugging.
#
-# Returns: VirtioQueueElement information
-#
# Since: 7.2
#
# Examples:
diff --git a/qapi/yank.json b/qapi/yank.json
index 89f2f4d199..82e3515308 100644
--- a/qapi/yank.json
+++ b/qapi/yank.json
@@ -102,8 +102,6 @@
#
# Query yank instances. See @YankInstance for more information.
#
-# Returns: list of @YankInstance
-#
# Example:
#
# -> { "execute": "query-yank" }
--
2.44.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PULL 5/7] qapi: Rename QAPISchemaAlternateType.variants to .alternatives
2024-05-06 11:02 [PULL 0/7] QAPI patches patches for 2024-05-06 Markus Armbruster
` (8 preceding siblings ...)
2024-05-06 11:02 ` [PATCH 5/7] qapi: Drop "Returns" section where default is fine WIP Markus Armbruster
@ 2024-05-06 11:02 ` Markus Armbruster
2024-05-06 11:02 ` [PULL 6/7] qapi: Move conditional code from QAPISchemaVariants to its subtypes Markus Armbruster
` (4 subsequent siblings)
14 siblings, 0 replies; 25+ messages in thread
From: Markus Armbruster @ 2024-05-06 11:02 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson
A previous commit narrowed the type of
QAPISchemaAlternateType.variants from QAPISchemaVariants to
QAPISchemaAlternatives. Rename it to .alternatives.
Same for .__init__() parameter @variants.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
scripts/qapi/schema.py | 25 +++++++++++++------------
1 file changed, 13 insertions(+), 12 deletions(-)
diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py
index c9ff794d0c..9bdbfd52b2 100644
--- a/scripts/qapi/schema.py
+++ b/scripts/qapi/schema.py
@@ -651,25 +651,25 @@ def __init__(
doc: Optional[QAPIDoc],
ifcond: Optional[QAPISchemaIfCond],
features: List[QAPISchemaFeature],
- variants: QAPISchemaAlternatives,
+ alternatives: QAPISchemaAlternatives,
):
super().__init__(name, info, doc, ifcond, features)
- assert variants.tag_member
- variants.set_defined_in(name)
- variants.tag_member.set_defined_in(self.name)
- self.variants = variants
+ assert alternatives.tag_member
+ alternatives.set_defined_in(name)
+ alternatives.tag_member.set_defined_in(self.name)
+ self.alternatives = alternatives
def check(self, schema: QAPISchema) -> None:
super().check(schema)
- self.variants.tag_member.check(schema)
- # Not calling self.variants.check_clash(), because there's nothing
- # to clash with
- self.variants.check(schema, {})
+ self.alternatives.tag_member.check(schema)
+ # Not calling self.alternatives.check_clash(), because there's
+ # nothing to clash with
+ self.alternatives.check(schema, {})
# Alternate branch names have no relation to the tag enum values;
# so we have to check for potential name collisions ourselves.
seen: Dict[str, QAPISchemaMember] = {}
types_seen: Dict[str, str] = {}
- for v in self.variants.variants:
+ for v in self.alternatives.variants:
v.check_clash(self.info, seen)
qtype = v.type.alternate_qtype()
if not qtype:
@@ -700,7 +700,7 @@ def check(self, schema: QAPISchema) -> None:
def connect_doc(self, doc: Optional[QAPIDoc] = None) -> None:
super().connect_doc(doc)
doc = doc or self.doc
- for v in self.variants.variants:
+ for v in self.alternatives.variants:
v.connect_doc(doc)
def c_type(self) -> str:
@@ -712,7 +712,8 @@ def json_type(self) -> str:
def visit(self, visitor: QAPISchemaVisitor) -> None:
super().visit(visitor)
visitor.visit_alternate_type(
- self.name, self.info, self.ifcond, self.features, self.variants)
+ self.name, self.info, self.ifcond, self.features,
+ self.alternatives)
class QAPISchemaVariants:
--
2.44.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PULL 6/7] qapi: Move conditional code from QAPISchemaVariants to its subtypes
2024-05-06 11:02 [PULL 0/7] QAPI patches patches for 2024-05-06 Markus Armbruster
` (9 preceding siblings ...)
2024-05-06 11:02 ` [PULL 5/7] qapi: Rename QAPISchemaAlternateType.variants to .alternatives Markus Armbruster
@ 2024-05-06 11:02 ` Markus Armbruster
2024-05-06 11:02 ` [PATCH 6/7] qga/qapi-schema: Drop "Returns" section where default is fine WIP Markus Armbruster
` (3 subsequent siblings)
14 siblings, 0 replies; 25+ messages in thread
From: Markus Armbruster @ 2024-05-06 11:02 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson
QAPISchemaVariants.check()'s code is almost entirely conditional on
union vs. alternate type.
Move the conditional code to QAPISchemaBranches.check() and
QAPISchemaAlternatives.check(), where the conditions are always
satisfied.
Attribute QAPISchemaVariants.tag_name is now only used by
QAPISchemaBranches. Move it there.
Refactor the three types' .__init__() to make them a bit simpler.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
scripts/qapi/schema.py | 138 ++++++++++++++++++++---------------------
1 file changed, 69 insertions(+), 69 deletions(-)
diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py
index 9bdbfd52b2..c5b824f1fd 100644
--- a/scripts/qapi/schema.py
+++ b/scripts/qapi/schema.py
@@ -719,20 +719,11 @@ def visit(self, visitor: QAPISchemaVisitor) -> None:
class QAPISchemaVariants:
def __init__(
self,
- tag_name: Optional[str],
info: QAPISourceInfo,
- tag_member: Optional[QAPISchemaObjectTypeMember],
variants: List[QAPISchemaVariant],
):
- # Unions pass tag_name but not tag_member.
- # Alternates pass tag_member but not tag_name.
- # After check(), tag_member is always set.
- assert bool(tag_member) != bool(tag_name)
- assert (isinstance(tag_name, str) or
- isinstance(tag_member, QAPISchemaObjectTypeMember))
- self._tag_name = tag_name
self.info = info
- self._tag_member = tag_member
+ self._tag_member: Optional[QAPISchemaObjectTypeMember] = None
self.variants = variants
@property
@@ -749,58 +740,66 @@ def set_defined_in(self, name: str) -> None:
v.set_defined_in(name)
def check(
- self, schema: QAPISchema, seen: Dict[str, QAPISchemaMember]
+ self, schema: QAPISchema, seen: Dict[str, QAPISchemaMember]
) -> None:
- if self._tag_name: # union
- # We need to narrow the member type:
- tmp = seen.get(c_name(self._tag_name))
- assert tmp is None or isinstance(tmp, QAPISchemaObjectTypeMember)
- self._tag_member = tmp
+ for v in self.variants:
+ v.check(schema)
- base = "'base'"
- # Pointing to the base type when not implicit would be
- # nice, but we don't know it here
- if not self._tag_member or self._tag_name != self._tag_member.name:
- raise QAPISemError(
- self.info,
- "discriminator '%s' is not a member of %s"
- % (self._tag_name, base))
- # Here we do:
- assert self.tag_member.defined_in
- base_type = schema.lookup_type(self.tag_member.defined_in)
- assert base_type
- if not base_type.is_implicit():
- base = "base type '%s'" % self.tag_member.defined_in
- if not isinstance(self.tag_member.type, QAPISchemaEnumType):
- raise QAPISemError(
- self.info,
- "discriminator member '%s' of %s must be of enum type"
- % (self._tag_name, base))
- if self.tag_member.optional:
- raise QAPISemError(
- self.info,
- "discriminator member '%s' of %s must not be optional"
- % (self._tag_name, base))
- if self.tag_member.ifcond.is_present():
- raise QAPISemError(
- self.info,
- "discriminator member '%s' of %s must not be conditional"
- % (self._tag_name, base))
- else: # alternate
- assert self._tag_member
- assert isinstance(self.tag_member.type, QAPISchemaEnumType)
- assert not self.tag_member.optional
- assert not self.tag_member.ifcond.is_present()
- if self._tag_name: # union
- # branches that are not explicitly covered get an empty type
- assert self.tag_member.defined_in
- cases = {v.name for v in self.variants}
- for m in self.tag_member.type.members:
- if m.name not in cases:
- v = QAPISchemaVariant(m.name, self.info,
- 'q_empty', m.ifcond)
- v.set_defined_in(self.tag_member.defined_in)
- self.variants.append(v)
+
+class QAPISchemaBranches(QAPISchemaVariants):
+ def __init__(self,
+ info: QAPISourceInfo,
+ variants: List[QAPISchemaVariant],
+ tag_name: str):
+ super().__init__(info, variants)
+ self._tag_name = tag_name
+
+ def check(
+ self, schema: QAPISchema, seen: Dict[str, QAPISchemaMember]
+ ) -> None:
+ # We need to narrow the member type:
+ tmp = seen.get(c_name(self._tag_name))
+ assert tmp is None or isinstance(tmp, QAPISchemaObjectTypeMember)
+ self._tag_member = tmp
+
+ base = "'base'"
+ # Pointing to the base type when not implicit would be
+ # nice, but we don't know it here
+ if not self._tag_member or self._tag_name != self._tag_member.name:
+ raise QAPISemError(
+ self.info,
+ "discriminator '%s' is not a member of %s"
+ % (self._tag_name, base))
+ # Here we do:
+ assert self.tag_member.defined_in
+ base_type = schema.lookup_type(self.tag_member.defined_in)
+ assert base_type
+ if not base_type.is_implicit():
+ base = "base type '%s'" % self.tag_member.defined_in
+ if not isinstance(self.tag_member.type, QAPISchemaEnumType):
+ raise QAPISemError(
+ self.info,
+ "discriminator member '%s' of %s must be of enum type"
+ % (self._tag_name, base))
+ if self.tag_member.optional:
+ raise QAPISemError(
+ self.info,
+ "discriminator member '%s' of %s must not be optional"
+ % (self._tag_name, base))
+ if self.tag_member.ifcond.is_present():
+ raise QAPISemError(
+ self.info,
+ "discriminator member '%s' of %s must not be conditional"
+ % (self._tag_name, base))
+ # branches that are not explicitly covered get an empty type
+ assert self.tag_member.defined_in
+ cases = {v.name for v in self.variants}
+ for m in self.tag_member.type.members:
+ if m.name not in cases:
+ v = QAPISchemaVariant(m.name, self.info,
+ 'q_empty', m.ifcond)
+ v.set_defined_in(self.tag_member.defined_in)
+ self.variants.append(v)
if not self.variants:
raise QAPISemError(self.info, "union has no branches")
for v in self.variants:
@@ -834,20 +833,21 @@ def check_clash(
v.type.check_clash(info, dict(seen))
-class QAPISchemaBranches(QAPISchemaVariants):
- def __init__(self,
- info: QAPISourceInfo,
- variants: List[QAPISchemaVariant],
- tag_name: str):
- super().__init__(tag_name, info, None, variants)
-
-
class QAPISchemaAlternatives(QAPISchemaVariants):
def __init__(self,
info: QAPISourceInfo,
variants: List[QAPISchemaVariant],
tag_member: QAPISchemaObjectTypeMember):
- super().__init__(None, info, tag_member, variants)
+ super().__init__(info, variants)
+ self._tag_member = tag_member
+
+ def check(
+ self, schema: QAPISchema, seen: Dict[str, QAPISchemaMember]
+ ) -> None:
+ super().check(schema, seen)
+ assert isinstance(self.tag_member.type, QAPISchemaEnumType)
+ assert not self.tag_member.optional
+ assert not self.tag_member.ifcond.is_present()
class QAPISchemaMember:
--
2.44.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH 6/7] qga/qapi-schema: Drop "Returns" section where default is fine WIP
2024-05-06 11:02 [PULL 0/7] QAPI patches patches for 2024-05-06 Markus Armbruster
` (10 preceding siblings ...)
2024-05-06 11:02 ` [PULL 6/7] qapi: Move conditional code from QAPISchemaVariants to its subtypes Markus Armbruster
@ 2024-05-06 11:02 ` Markus Armbruster
2024-05-06 12:47 ` Markus Armbruster
2024-05-06 11:02 ` [PATCH 7/7] find untagged sections WIP Markus Armbruster
` (2 subsequent siblings)
14 siblings, 1 reply; 25+ messages in thread
From: Markus Armbruster @ 2024-05-06 11:02 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson
---
qga/qapi-schema.json | 40 +++++-----------------------------------
1 file changed, 5 insertions(+), 35 deletions(-)
diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index d5af155007..fe41670ed2 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -194,8 +194,6 @@
#
# Get some information about the guest agent.
#
-# Returns: @GuestAgentInfo
-#
# Since: 0.15.0
##
{ 'command': 'guest-info',
@@ -277,8 +275,6 @@
# @count: maximum number of bytes to read (default is 4KB, maximum is
# 48MB)
#
-# Returns: @GuestFileRead
-#
# Since: 0.15.0
##
{ 'command': 'guest-file-read',
@@ -312,8 +308,6 @@
# @count: bytes to write (actual bytes, after base64-decode), default
# is all content in buf-b64 buffer after base64 decoding
#
-# Returns: @GuestFileWrite
-#
# Since: 0.15.0
##
{ 'command': 'guest-file-write',
@@ -379,8 +373,6 @@
#
# @whence: Symbolic or numeric code for interpreting offset
#
-# Returns: @GuestFileSeek
-#
# Since: 0.15.0
##
{ 'command': 'guest-file-seek',
@@ -419,9 +411,6 @@
#
# Get guest fsfreeze state.
#
-# Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined
-# below)
-#
# Note: This may fail to properly report the current state as a result
# of some other guest processes having issued an fs freeze/thaw.
#
@@ -725,8 +714,6 @@
#
# Get list of guest IP addresses, MAC addresses and netmasks.
#
-# Returns: List of GuestNetworkInterface
-#
# Since: 1.1
##
{ 'command': 'guest-network-get-interfaces',
@@ -760,6 +747,7 @@
#
# Returns: The list of all VCPUs the guest knows about. Each VCPU is
# put on the list exactly once, but their order is unspecified.
+# TODO
#
# Since: 1.5
##
@@ -1009,6 +997,7 @@
# the physical disks. On Linux these are all root block devices
# of non-zero size including e.g. removable devices, loop devices,
# NBD, etc.
+# TODO
#
# Since: 5.2
##
@@ -1045,6 +1034,7 @@
# The returned mountpoints may be specified to
# @guest-fsfreeze-freeze-list. Network filesystems (such as CIFS
# and NFS) are not listed.
+# TODO
#
# Since: 2.2
##
@@ -1108,6 +1098,7 @@
# Returns: The list of all memory blocks the guest knows about. Each
# memory block is put on the list exactly once, but their order is
# unspecified.
+# TODO
#
# Since: 2.3
##
@@ -1179,6 +1170,7 @@
# Note: it will return an empty list if the @mem-blks list was
# empty on input, or there is an error, and in this case, guest
# state will not be changed.
+# TODO
#
# Since: 2.3
##
@@ -1203,8 +1195,6 @@
#
# Get information relating to guest memory blocks.
#
-# Returns: @GuestMemoryBlockInfo
-#
# Since: 2.3
##
{ 'command': 'guest-get-memory-block-info',
@@ -1249,8 +1239,6 @@
#
# @pid: pid returned from guest-exec
#
-# Returns: GuestExecStatus
-#
# Since: 2.5
##
{ 'command': 'guest-exec-status',
@@ -1322,8 +1310,6 @@
# @capture-output: bool flag to enable capture of stdout/stderr of
# running process. Defaults to false.
#
-# Returns: PID
-#
# Since: 2.5
##
{ 'command': 'guest-exec',
@@ -1351,8 +1337,6 @@
# or even present in DNS or some other name service at all. It need
# not even be unique on your local network or site, but usually it is.
#
-# Returns: the host name of the machine
-#
# Since: 2.10
##
{ 'command': 'guest-get-host-name',
@@ -1381,8 +1365,6 @@
#
# Retrieves a list of currently active users on the VM.
#
-# Returns: A unique list of users.
-#
# Since: 2.10
##
{ 'command': 'guest-get-users',
@@ -1407,8 +1389,6 @@
#
# Retrieves the timezone information from the guest.
#
-# Returns: A GuestTimezone dictionary.
-#
# Since: 2.10
##
{ 'command': 'guest-get-timezone',
@@ -1483,8 +1463,6 @@
#
# Retrieve guest operating system information
#
-# Returns: @GuestOSInfo
-#
# Since: 2.10
##
{ 'command': 'guest-get-osinfo',
@@ -1550,8 +1528,6 @@
#
# Retrieve information about device drivers in Windows guest
#
-# Returns: @GuestDeviceInfo
-#
# Since: 5.2
##
{ 'command': 'guest-get-devices',
@@ -1579,8 +1555,6 @@
#
# @username: the user account to add the authorized keys
#
-# Returns: @GuestAuthorizedKeys
-#
# Since: 5.2
##
{ 'command': 'guest-ssh-get-authorized-keys',
@@ -1707,8 +1681,6 @@
#
# Retrieve information about disk stats.
#
-# Returns: List of disk stats of guest.
-#
# Since: 7.1
##
{ 'command': 'guest-get-diskstats',
@@ -1791,8 +1763,6 @@
#
# Retrieve information about CPU stats.
#
-# Returns: List of CPU stats of guest.
-#
# Since: 7.1
##
{ 'command': 'guest-get-cpustats',
--
2.44.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PATCH 7/7] find untagged sections WIP
2024-05-06 11:02 [PULL 0/7] QAPI patches patches for 2024-05-06 Markus Armbruster
` (11 preceding siblings ...)
2024-05-06 11:02 ` [PATCH 6/7] qga/qapi-schema: Drop "Returns" section where default is fine WIP Markus Armbruster
@ 2024-05-06 11:02 ` Markus Armbruster
2024-05-06 12:47 ` Markus Armbruster
2024-05-06 11:02 ` [PULL 7/7] qapi: Simplify QAPISchemaVariants @tag_member Markus Armbruster
2024-05-06 19:58 ` [PULL 0/7] QAPI patches patches for 2024-05-06 Richard Henderson
14 siblings, 1 reply; 25+ messages in thread
From: Markus Armbruster @ 2024-05-06 11:02 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson
---
qapi/block-core.json | 1 +
qapi/introspect.json | 4 ++++
qapi/machine-target.json | 2 ++
qapi/migration.json | 3 +++
qapi/net.json | 2 ++
qapi/qom.json | 1 +
qapi/ui.json | 1 +
qga/qapi-schema.json | 2 ++
scripts/qapi/parser.py | 1 +
tests/qapi-schema/doc-good.out | 1 +
10 files changed, 18 insertions(+)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index fab1a45365..1c43d3d2bb 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -3289,6 +3289,7 @@
#
# @namespace: namespace number of the device, starting from 1.
#
+# @@@ untagged
# Note that the PCI @device must have been unbound from any host
# kernel driver before instructing QEMU to add the blockdev.
#
diff --git a/qapi/introspect.json b/qapi/introspect.json
index b041b02ba8..1747562a41 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -149,6 +149,7 @@
#
# @deprecated: Member @values is deprecated. Use @members instead.
#
+# @@@ untagged
# Values of this type are JSON string on the wire.
#
# Since: 2.5
@@ -180,6 +181,7 @@
#
# @element-type: the array type's element type.
#
+# @@@ untagged
# Values of this type are JSON array on the wire.
#
# Since: 2.5
@@ -203,6 +205,7 @@
# The variants are in no particular order, and may even differ
# from the order of the values of the enum type of the @tag.
#
+# @@@ untagged
# Values of this type are JSON object on the wire.
#
# Since: 2.5
@@ -261,6 +264,7 @@
# members' wire encoding is distinct, see
# :doc:`/devel/qapi-code-gen` section Alternate types.
#
+# @@@ untagged
# On the wire, this can be any of the members.
#
# Since: 2.5
diff --git a/qapi/machine-target.json b/qapi/machine-target.json
index 4ef7ef7b43..37ffd6409b 100644
--- a/qapi/machine-target.json
+++ b/qapi/machine-target.json
@@ -107,6 +107,7 @@
# @responsible-properties: List of properties that led to the
# comparison result not being identical.
#
+# @@@ untagged
# @responsible-properties is a list of QOM property names that led to
# both CPUs not being detected as identical. For identical models,
# this list is empty. If a QOM property is read-only, that means
@@ -342,6 +343,7 @@
# removed in in some future version of QEMU according to the QEMU
# deprecation policy. (since 5.2)
#
+# @@@ untagged
# @unavailable-features is a list of QOM property names that represent
# CPU model attributes that prevent the CPU from running. If the QOM
# property is read-only, that means there's no known way to make the
diff --git a/qapi/migration.json b/qapi/migration.json
index e22645253c..97a727c41a 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -2427,6 +2427,7 @@
#
# @devices: list of block device node names to save a snapshot to
#
+# @@@ untagged
# Applications should not assume that the snapshot save is complete
# when this command returns. The job commands / events must be used
# to determine completion and to fetch details of any errors that
@@ -2499,6 +2500,7 @@
#
# @devices: list of block device node names to load a snapshot from
#
+# @@@ untagged
# Applications should not assume that the snapshot load is complete
# when this command returns. The job commands / events must be used
# to determine completion and to fetch details of any errors that
@@ -2567,6 +2569,7 @@
#
# @devices: list of block device node names to delete a snapshot from
#
+# @@@ untagged
# Applications should not assume that the snapshot delete is complete
# when this command returns. The job commands / events must be used
# to determine completion and to fetch details of any errors that
diff --git a/qapi/net.json b/qapi/net.json
index 0f5a259475..da21c02fa2 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -650,6 +650,7 @@
# attempt a reconnect after the given number of seconds. Setting
# this to zero disables this function. (default: 0) (since 8.0)
#
+# @@@ untagged
# Only SocketAddress types 'unix', 'inet' and 'fd' are supported.
#
# Since: 7.2
@@ -669,6 +670,7 @@
#
# @local: local address
#
+# @@@ untagged
# Only SocketAddress types 'unix', 'inet' and 'fd' are supported.
#
# If remote address is present and it's a multicast address, local
diff --git a/qapi/qom.json b/qapi/qom.json
index d1dc216474..237711cd59 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -547,6 +547,7 @@
# algorithm detects it is spending too long polling without
# encountering events. 0 selects a default behaviour (default: 0)
#
+# @@@ untagged
# The @aio-max-batch option is available since 6.1.
#
# Since: 2.0
diff --git a/qapi/ui.json b/qapi/ui.json
index 2b7f0b8401..b2c3f143dc 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -934,6 +934,7 @@
#
# @f24: since 8.0
#
+# @@@ untagged
# 'sysrq' was mistakenly added to hack around the fact that the ps2
# driver was not generating correct scancodes sequences when
# 'alt+print' was pressed. This flaw is now fixed and the 'sysrq' key
diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index fe41670ed2..17cdb52f83 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -207,6 +207,7 @@
#
# @mode: "halt", "powerdown" (default), or "reboot"
#
+# @@@ untagged
# This command does NOT return a response on success. Success
# condition is indicated by the VM exiting with a zero exit status or,
# when running with --no-shutdown, by issuing the query-status QMP
@@ -1050,6 +1051,7 @@
#
# @crypted: true if password is already crypt()d, false if raw
#
+# @@@ untagged
# If the @crypted flag is true, it is the caller's responsibility to
# ensure the correct crypt() encryption scheme is used. This command
# does not attempt to interpret or report on the encryption scheme.
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index e8a482c37d..126acab38d 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -665,6 +665,7 @@ def ensure_untagged_section(self, info: QAPISourceInfo) -> None:
section = self.Section(info)
self.sections.append(section)
self.all_sections.append(section)
+ section.append_line(f'### untagged {info.loc()}')
def new_tagged_section(self, info: QAPISourceInfo, tag: str) -> None:
section = self.Section(info, tag)
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index f2be711a2c..067e3d1135 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -112,6 +112,7 @@ Also _one_ {and only}
feature=enum-member-feat
a member feature
section=None
+### untagged /work/armbru/qemu/bld/../tests/qapi-schema/doc-good.json:67
@two is undocumented
doc symbol=Base
body=
--
2.44.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* [PULL 7/7] qapi: Simplify QAPISchemaVariants @tag_member
2024-05-06 11:02 [PULL 0/7] QAPI patches patches for 2024-05-06 Markus Armbruster
` (12 preceding siblings ...)
2024-05-06 11:02 ` [PATCH 7/7] find untagged sections WIP Markus Armbruster
@ 2024-05-06 11:02 ` Markus Armbruster
2024-05-06 19:58 ` [PULL 0/7] QAPI patches patches for 2024-05-06 Richard Henderson
14 siblings, 0 replies; 25+ messages in thread
From: Markus Armbruster @ 2024-05-06 11:02 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson
For union types, the tag member is known only after .check().
We used to code this in a simple way: QAPISchemaVariants attribute
.tag_member was None for union types until .check().
Since this complicated typing, recent commit "qapi/schema: fix typing
for QAPISchemaVariants.tag_member" hid it behind a property.
The previous commit lets us treat .tag_member just like the other
attributes that become known only in .check(): declare, but don't
initialize it in .__init__().
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
scripts/qapi/schema.py | 44 +++++++++++++++++-------------------------
1 file changed, 18 insertions(+), 26 deletions(-)
diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py
index c5b824f1fd..721c470d2b 100644
--- a/scripts/qapi/schema.py
+++ b/scripts/qapi/schema.py
@@ -723,18 +723,9 @@ def __init__(
variants: List[QAPISchemaVariant],
):
self.info = info
- self._tag_member: Optional[QAPISchemaObjectTypeMember] = None
+ self.tag_member: QAPISchemaObjectTypeMember
self.variants = variants
- @property
- def tag_member(self) -> QAPISchemaObjectTypeMember:
- if self._tag_member is None:
- raise RuntimeError(
- "QAPISchemaVariants has no tag_member property until "
- "after check() has been run."
- )
- return self._tag_member
-
def set_defined_in(self, name: str) -> None:
for v in self.variants:
v.set_defined_in(name)
@@ -758,47 +749,48 @@ def check(
self, schema: QAPISchema, seen: Dict[str, QAPISchemaMember]
) -> None:
# We need to narrow the member type:
- tmp = seen.get(c_name(self._tag_name))
- assert tmp is None or isinstance(tmp, QAPISchemaObjectTypeMember)
- self._tag_member = tmp
+ tag_member = seen.get(c_name(self._tag_name))
+ assert (tag_member is None
+ or isinstance(tag_member, QAPISchemaObjectTypeMember))
base = "'base'"
# Pointing to the base type when not implicit would be
# nice, but we don't know it here
- if not self._tag_member or self._tag_name != self._tag_member.name:
+ if not tag_member or self._tag_name != tag_member.name:
raise QAPISemError(
self.info,
"discriminator '%s' is not a member of %s"
% (self._tag_name, base))
+ self.tag_member = tag_member
# Here we do:
- assert self.tag_member.defined_in
- base_type = schema.lookup_type(self.tag_member.defined_in)
+ assert tag_member.defined_in
+ base_type = schema.lookup_type(tag_member.defined_in)
assert base_type
if not base_type.is_implicit():
- base = "base type '%s'" % self.tag_member.defined_in
- if not isinstance(self.tag_member.type, QAPISchemaEnumType):
+ base = "base type '%s'" % tag_member.defined_in
+ if not isinstance(tag_member.type, QAPISchemaEnumType):
raise QAPISemError(
self.info,
"discriminator member '%s' of %s must be of enum type"
% (self._tag_name, base))
- if self.tag_member.optional:
+ if tag_member.optional:
raise QAPISemError(
self.info,
"discriminator member '%s' of %s must not be optional"
% (self._tag_name, base))
- if self.tag_member.ifcond.is_present():
+ if tag_member.ifcond.is_present():
raise QAPISemError(
self.info,
"discriminator member '%s' of %s must not be conditional"
% (self._tag_name, base))
# branches that are not explicitly covered get an empty type
- assert self.tag_member.defined_in
+ assert tag_member.defined_in
cases = {v.name for v in self.variants}
- for m in self.tag_member.type.members:
+ for m in tag_member.type.members:
if m.name not in cases:
v = QAPISchemaVariant(m.name, self.info,
'q_empty', m.ifcond)
- v.set_defined_in(self.tag_member.defined_in)
+ v.set_defined_in(tag_member.defined_in)
self.variants.append(v)
if not self.variants:
raise QAPISemError(self.info, "union has no branches")
@@ -807,11 +799,11 @@ def check(
# Union names must match enum values; alternate names are
# checked separately. Use 'seen' to tell the two apart.
if seen:
- if v.name not in self.tag_member.type.member_names():
+ if v.name not in tag_member.type.member_names():
raise QAPISemError(
self.info,
"branch '%s' is not a value of %s"
- % (v.name, self.tag_member.type.describe()))
+ % (v.name, tag_member.type.describe()))
if not isinstance(v.type, QAPISchemaObjectType):
raise QAPISemError(
self.info,
@@ -839,7 +831,7 @@ def __init__(self,
variants: List[QAPISchemaVariant],
tag_member: QAPISchemaObjectTypeMember):
super().__init__(info, variants)
- self._tag_member = tag_member
+ self.tag_member = tag_member
def check(
self, schema: QAPISchema, seen: Dict[str, QAPISchemaMember]
--
2.44.0
^ permalink raw reply related [flat|nested] 25+ messages in thread* Re: [PULL 0/7] QAPI patches patches for 2024-05-06
2024-05-06 11:02 [PULL 0/7] QAPI patches patches for 2024-05-06 Markus Armbruster
` (13 preceding siblings ...)
2024-05-06 11:02 ` [PULL 7/7] qapi: Simplify QAPISchemaVariants @tag_member Markus Armbruster
@ 2024-05-06 19:58 ` Richard Henderson
14 siblings, 0 replies; 25+ messages in thread
From: Richard Henderson @ 2024-05-06 19:58 UTC (permalink / raw)
To: Markus Armbruster, qemu-devel
On 5/6/24 04:02, Markus Armbruster wrote:
> The following changes since commit 248f6f62df073a3b4158fd0093863ab885feabb5:
>
> Merge tag 'pull-axp-20240504' ofhttps://gitlab.com/rth7680/qemu into staging (2024-05-04 08:39:46 -0700)
>
> are available in the Git repository at:
>
> https://repo.or.cz/qemu/armbru.git tags/pull-qapi-2024-05-06
>
> for you to fetch changes up to 285a8f209af7b4992aa91e8bea03a303fb6406ab:
>
> qapi: Simplify QAPISchemaVariants @tag_member (2024-05-06 12:38:27 +0200)
>
> ----------------------------------------------------------------
> QAPI patches patches for 2024-05-06
Applied, thanks. Please update https://wiki.qemu.org/ChangeLog/9.1 as appropriate.
r~
^ permalink raw reply [flat|nested] 25+ messages in thread