Re: [PATCH v6 1/4] docs/qapi-domain: add return-nodesc

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> This form is used to annotate a return type without an accompanying
> description, for when there is no "Returns:" information in the source
> doc, but we have a return type we want to generate a cross-reference to.
>
> The syntax is:
>
> :return-nodesc: TypeName
>
> It's primarily necessary because Sphinx always expects both a type and a
> description for the prior form and will format it accordingly. To have a
> reasonable rendering when the body is missing, we need to use a
> different info field list entirely.
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  docs/devel/qapi-domain.rst | 30 ++++++++++++++++++++++++++++++
>  docs/sphinx/qapi_domain.py |  8 ++++++++
>  2 files changed, 38 insertions(+)
>
> diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst
> index 11238723c2d..204abb72ff4 100644
> --- a/docs/devel/qapi-domain.rst
> +++ b/docs/devel/qapi-domain.rst
> @@ -242,6 +242,36 @@ Example::
>               }
>  
>  
> +``:return-nodesc:``
> +-------------------
> +
> +Document the return type of a QAPI command, without an accompanying description.

Recommend to break the long line.

> +
> +:availability: This field list is only available in the body of the
> +               Command directive.
> +:syntax: ``:return-nodesc: type``
> +:type: `sphinx.util.docfields.Field
> +       <https://pydoc.dev/sphinx/latest/sphinx.util.docfields.Field.html?private=1>`_
> +
> +
> +Example::
> +
> +   .. qapi:command:: query-replay
> +      :since: 5.2
> +
> +      Retrieve the record/replay information.  It includes current
> +      instruction count which may be used for ``replay-break`` and
> +      ``replay-seek`` commands.
> +
> +      :return-nodesc: ReplayInfo
> +
> +      .. qmp-example::
> +
> +          -> { "execute": "query-replay" }
> +          <- { "return": {
> +                 "mode": "play", "filename": "log.rr", "icount": 220414 }
> +             }
> +

Same example as in :return:, except for the :return-nodesc: line.  Fine
with me.

>  ``:value:``
>  -----------
>  
> diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
> index ebc46a72c61..f561dc465f8 100644
> --- a/docs/sphinx/qapi_domain.py
> +++ b/docs/sphinx/qapi_domain.py
> @@ -532,6 +532,14 @@ class QAPICommand(QAPIObject):
>                  names=("return",),
>                  can_collapse=True,
>              ),
> +            # :return-nodesc: TypeName
> +            CompatField(
> +                "returnvalue",
> +                label=_("Return"),
> +                names=("return-nodesc",),
> +                bodyrolename="type",
> +                has_arg=False,
> +            ),
>          ]
>      )

Acked-by: Markus Armbruster <armbru@redhat.com>