[v1] docs: Add new QAPI transmogrifier

[PATCH 48/57] docs/qapidoc: add visit_returns() method

Posted by John Snow 4 weeks ago

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 <jsnow@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
+        assert section.text  # We don't expect empty returns sections.
+        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
-- 
2.48.1

Re: [PATCH 48/57] docs/qapidoc: add visit_returns() method

Posted by Markus Armbruster 3 weeks, 5 days ago

John Snow <jsnow@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 <jsnow@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
> +        assert section.text  # We don't expect empty returns sections.

Not sure the comment is worth its keep.  Up to you.

> +        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

Re: [PATCH 48/57] docs/qapidoc: add visit_returns() method

Posted by John Snow 3 weeks, 4 days ago

On Fri, Mar 7, 2025 at 7:18 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@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 <jsnow@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
>
>