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 <js...@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 a748529f515..5ca060fa04c 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 c94af5719ca..d6d4a70f3df 100644
--- a/docs/sphinx/qapi_domain.py
+++ b/docs/sphinx/qapi_domain.py
@@ -529,6 +529,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.48.1
