This patch adds support for handling undocumented returns values
sections -- which aren't actually implemented until the next patch.
Signed-off-by: John Snow <js...@redhat.com>
---
docs/sphinx/qapidoc.py | 20 +++++++++++++-------
1 file changed, 13 insertions(+), 7 deletions(-)
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 538c26e812d..b9fe2f476cb 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -410,15 +410,21 @@ def visit_feature(self, section: QAPIDoc.ArgSection) ->
None:
def visit_returns(self, section: QAPIDoc.Section) -> None:
assert isinstance(self.entity, QAPISchemaCommand)
rtype = self.entity.ret_type
- # q_empty can produce None, but we won't be documenting anything
- # without an explicit return statement in the doc block, and we
- # should not have any such explicit statements when there is no
- # return value.
- assert rtype
+
+ if not rtype:
+ # Markus prefers q_empty returning commands just say
+ # nothing. I'd like a "Returns nothing" in the generated
+ # docs because I like explicit to implicit - Users may not
+ # know that commands have an implicit return type and may
+ # wrongly assume that a missing "Returns" statement means
+ # it's undocumented. Well, that's my $0.02.
+ return
typ = self.format_type(rtype)
- assert section.text # We don't expect empty returns sections.
- self.add_field("returns", typ, section.text, section.info)
+ if section.text:
+ self.add_field("returns", typ, section.text, section.info)
+ else:
+ self.add_lines(f":returns-nodesc: {typ}", section.info)
def visit_errors(self, section: QAPIDoc.Section) -> None:
# FIXME: the formatting for errors may be inconsistent and may
--
2.48.1
