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