| Message ID | 20250309083550.5155-19-jsnow@redhat.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | docs: Add new QAPI transmogrifier | expand |
John Snow <jsnow@redhat.com> writes: > 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. > > This patch adds "Return" 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." > > Signed-off-by: John Snow <jsnow@redhat.com> Mention the new syntax :return like PATCH 15 does for :arg? > --- > 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 d018fcd4f7c..8a364ff75ea 100644 > --- a/docs/sphinx/qapi_domain.py > +++ b/docs/sphinx/qapi_domain.py > @@ -296,6 +296,13 @@ class QAPICommand(QAPIObject): > names=("error", "errors"), > has_arg=False, > ), > + # :returns TypeName: descr :return I believe. > + GroupedField( > + "returnvalue", > + label=_("Return"), > + names=("return",), > + can_collapse=True, > + ), > ] > )
diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index d018fcd4f7c..8a364ff75ea 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -296,6 +296,13 @@ class QAPICommand(QAPIObject): names=("error", "errors"), has_arg=False, ), + # :returns TypeName: descr + GroupedField( + "returnvalue", + label=_("Return"), + names=("return",), + can_collapse=True, + ), ] )
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. This patch adds "Return" 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." Signed-off-by: John Snow <jsnow@redhat.com> --- docs/sphinx/qapi_domain.py | 7 +++++++ 1 file changed, 7 insertions(+)