[PULL,16/61] docs/qapi-domain: add "Return:" field lists

Commit Message

Markus Armbruster March 11, 2025, 11:30 a.m. UTC

From: John Snow <[e-mail]>

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 <[e-mail]>
Message-ID: <[e-mail]>
Acked-by: Markus Armbruster <[e-mail]>
Signed-off-by: Markus Armbruster <[e-mail]>
---
 docs/sphinx/qapi_domain.py | 7 +++++++
 1 file changed, 7 insertions(+)

Patch

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,
+            ),
         ]
     )