John Snow <js...@redhat.com> writes: > This patch changes the qapidoc transmogrifier to generate Return value > documentation for any command that has a return value but hasn't > explicitly documented that return value. > > Signed-off-by: John Snow <js...@redhat.com>
[...] > diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py > index 949d9e8bff7..8c382a049af 100644 > --- a/scripts/qapi/parser.py > +++ b/scripts/qapi/parser.py > @@ -815,6 +815,17 @@ def connect_feature(self, feature: 'QAPISchemaFeature') > -> None: > % feature.name) > self.features[feature.name].connect(feature) > > + def ensure_returns(self, info: QAPISourceInfo) -> None: > + if not any(s.kind == QAPIDoc.Kind.RETURNS for s in > self.all_sections): > + > + # Stub "Returns" section for undocumented returns value. > + # Insert stub after the last non-PLAIN section. Can you explain why that's where it should go? Should we tighten section order some more? > + for sect in reversed(self.all_sections): > + if sect.kind != QAPIDoc.Kind.PLAIN: > + stub = QAPIDoc.Section(info, QAPIDoc.Kind.RETURNS) > + idx = self.all_sections.index(sect) + 1 > + self.all_sections.insert(idx, stub) > + > def check_expr(self, expr: QAPIExpression) -> None: > if 'command' in expr: > if self.returns and 'returns' not in expr: > diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py > index cbe3b5aa91e..3abddea3525 100644 > --- a/scripts/qapi/schema.py > +++ b/scripts/qapi/schema.py > @@ -1062,6 +1062,9 @@ def connect_doc(self, doc: Optional[QAPIDoc] = None) -> > None: > if self.arg_type and self.arg_type.is_implicit(): > self.arg_type.connect_doc(doc) > > + if self.ret_type and self.info: > + doc.ensure_returns(self.info) > + > def visit(self, visitor: QAPISchemaVisitor) -> None: > super().visit(visitor) > visitor.visit_command(
