John Snow <js...@redhat.com> writes:
> 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
"errors"?
> 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."
scripts/qapi/parser.py rejects duplicate 'Returns:' tags. So, to do the
thing you shouldn't do, you'd have to use the QAPI domain directly.
I doubt such shenanigans would survive review :)
> 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:-)
My personal taste is imperative mood, always.
Sadly, the QAPI schema language uses 'Returns:'.
The Sphinx Python Domain appears to use :return:.
I recommend to go for consistency with the Python Domain, and ditch
:returns:.
> Signed-off-by: John Snow <js...@redhat.com>
> ---
> docs/sphinx/qapi_domain.py | 7 +++++++
> 1 file changed, 7 insertions(+)
>
> diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
> index d60cccb8e95..7531bdfbba7 100644
> --- a/docs/sphinx/qapi_domain.py
> +++ b/docs/sphinx/qapi_domain.py
> @@ -292,6 +292,13 @@ class QAPICommand(QAPIObject):
> names=("error", "errors"),
> has_arg=False,
> ),
> + # :returns TypeName: descr
> + GroupedField(
> + "returnvalue",
> + label=_("Returns"),
> + names=("return", "returns"),
> + can_collapse=True,
> + ),
> ]
> )
