Add "Returns:" 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.
This patch adds "errors" as a GroupedField, which means that multiple return values can be annotated - this is only done because Sphinx does not seemingly (Maybe I missed it?) 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." Since this field describes an action/event instead of describing a list of nouns (arguments, features, errors), I added both the imperative and indicative forms (:return: and :returns:) to allow doc writers to use whichever mood "feels right" in the source document. The rendered output will always use the "Returns:" label, however. I'm sure you'll let me know how you feel about that. O:-) Signed-off-by: John Snow <js...@redhat.com> --- docs/qapi/index.rst | 2 ++ docs/sphinx/qapi-domain.py | 6 ++++++ 2 files changed, 8 insertions(+) diff --git a/docs/qapi/index.rst b/docs/qapi/index.rst index 004d02e0437..39fe4dd2dae 100644 --- a/docs/qapi/index.rst +++ b/docs/qapi/index.rst @@ -102,6 +102,8 @@ Explicit cross-referencing syntax for QAPI modules is available with isn't real. :error GenericError: If the system decides it doesn't like the argument values. It's very temperamental. + :return SomeTypeName: An esoteric collection of mystical nonsense to + both confound and delight. Field lists can appear anywhere in the directive block, but any field list entries in the same list block that are recognized as special diff --git a/docs/sphinx/qapi-domain.py b/docs/sphinx/qapi-domain.py index 1f0b168fa2c..5d44dba6cd3 100644 --- a/docs/sphinx/qapi-domain.py +++ b/docs/sphinx/qapi-domain.py @@ -279,6 +279,12 @@ class QAPICommand(QAPIObject): names=("error",), can_collapse=True, ), + GroupedField( + "returnvalue", + label=_("Returns"), + names=("return", "returns"), + can_collapse=True, + ), ] ) -- 2.44.0