John Snow <js...@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 <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 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 <arm...@redhat.com>
