On Fri, Mar 7, 2025 at 7:18 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@redhat.com> writes: > > > Generates :returns: fields for explicit returns statements. Note that > > this does not presently handle undocumented returns, which is handled in > > a later commit. > > > > Signed-off-by: John Snow <js...@redhat.com> > > --- > > docs/sphinx/qapidoc.py | 15 +++++++++++++++ > > 1 file changed, 15 insertions(+) > > > > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py > > index 834f12ba6e9..6458790fe55 100644 > > --- a/docs/sphinx/qapidoc.py > > +++ b/docs/sphinx/qapidoc.py > > @@ -41,6 +41,7 @@ > > from qapi.schema import ( > > QAPISchema, > > QAPISchemaArrayType, > > + QAPISchemaCommand, > > QAPISchemaDefinition, > > QAPISchemaEnumMember, > > QAPISchemaFeature, > > @@ -210,6 +211,20 @@ def visit_feature(self, section: > QAPIDoc.ArgSection) -> None: > > > > self.generate_field("feat", section.member, section.text, > section.info) > > > > + def visit_returns(self, section: QAPIDoc.Section) -> None: > > + assert isinstance(self.entity, QAPISchemaCommand) > > + rtype = self.entity.ret_type > > + # q_empty can produce None, but we won't be documenting anything > > + # without an explicit return statement in the doc block, and we > > + # should not have any such explicit statements when there is no > > + # return value. > > + assert rtype > > + > > + typ = self.format_type(rtype) > > + assert typ > I wonder if I can write "assert typ := self.format_type(rtype)" here. > > + assert section.text # We don't expect empty returns sections. > > Not sure the comment is worth its keep. Up to you. > Will remove. Not the first time I've talked to myself with assert messages. Something from the very, very early days of this project and I had to remind myself of some truths here and there (: > > > + self.add_field("returns", typ, section.text, section.info) > > + > > def visit_errors(self, section: QAPIDoc.Section) -> None: > > # FIXME: the formatting for errors may be inconsistent and may > > # or may not require different newline placement to ensure > >