From 8b77f8d5730003d868b5748af5438c43d17f8c3a Mon Sep 17 00:00:00 2001 From: John Snow Date: Mon, 10 Mar 2025 23:42:16 -0400 Subject: 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 --- docs/sphinx/qapi_domain.py | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs/sphinx/qapi_domain.py') diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 7535009..45e6968 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, + ), ] ) -- cgit v1.1