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.
+
+: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 }
+             }
+
 ``: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,
+            ),
         ]
     )
 
-- 
2.50.0

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>