From: John Snow Date: Tue, 11 Mar 2025 03:42:16 +0000 (-0400) Subject: docs/qapi-domain: add "Return:" field lists X-Git-Tag: v10.0.0-rc0~11^2~45 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=8b77f8d5730003d868b5748af5438c43d17f8c3a;p=thirdparty%2Fqemu.git docs/qapi-domain: add "Return:" field lists Add "Return:" field list syntax to QAPI Commands. Like "Arguments:" and "Errors:", the type name isn't currently processed for cross-referencing, but this will be addressed in a forthcoming commit. The syntax of the new field is: :return TypeName: description description cont'd This patch adds "Return" as a GroupedField, which means that multiple return values can be annotated - this is only done because Sphinx does not support mandatory type arguments to Ungrouped fields. Because we want to cross-reference this type information later, we want to make the type argument mandatory. As a result, you can technically add multiple :return: fields, though I'm not aware of any circumstance in which you'd need or want to. Recommendation: "Don't do that, then." The forthcoming QAPIDoc transmogrifier does not, in fact, ever "do that". Signed-off-by: John Snow Message-ID: <20250311034303.75779-19-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 7535009078..45e69689d1 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -301,6 +301,13 @@ class QAPICommand(QAPIObject): names=("error", "errors"), has_arg=False, ), + # :return TypeName: descr + GroupedField( + "returnvalue", + label=_("Return"), + names=("return",), + can_collapse=True, + ), ] )