[3/7] qapi: make returns sections special WIP

Commit Message

Markus Armbruster May 6, 2024, 11:02 a.m. UTC

returns moves in generated output
---
 docs/sphinx/qapidoc.py         |  8 ++++++++
 scripts/qapi/parser.py         |  4 ++--
 tests/qapi-schema/doc-good.out |  4 ++--
 tests/qapi-schema/doc-good.txt | 12 ++++++------
 tests/qapi-schema/test-qapi.py |  2 ++
 5 files changed, 20 insertions(+), 10 deletions(-)

Comments

Markus Armbruster May 6, 2024, 12:46 p.m. UTC | #1

Sent by accident, please ignore.

Patch

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index f19f5ded78..24bf1d9a90 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -250,6 +250,13 @@  def _nodes_for_features(self, doc):
         section += dlnode
         return [section]
 
+    def _nodes_for_returns(self, doc, ret_type):
+        if doc.returns:
+            section = self._make_section('Returns')
+            self._parse_text_into_node(doc.returns.text, section)
+            return [section]
+        return []
+
     def _nodes_for_since(self, doc):
         if doc.since:
             # TODO emphasis
@@ -343,6 +350,7 @@  def visit_command(self, name, info, ifcond, features, arg_type,
         self._add_doc('Command',
                       self._nodes_for_arguments(doc,
                                                 arg_type if boxed else None)
+                      + self._nodes_for_returns(doc, ret_type)
                       + self._nodes_for_features(doc)
                       + self._nodes_for_sections(doc)
                       + self._nodes_for_if_section(ifcond)
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 0237d13da9..e8a482c37d 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -646,7 +646,7 @@  def __init__(self, info: QAPISourceInfo, symbol: Optional[str] = None):
         self.errors: Optional[QAPIDoc.Section] = None
         # "Since" section
         self.since: Optional[QAPIDoc.Section] = None
-        # sections other than .body, .args, .features, .since
+        # sections other than .body, .args, .features, .returns, .since
         self.sections: List[QAPIDoc.Section] = []
 
     def end(self) -> None:
@@ -683,7 +683,7 @@  def new_tagged_section(self, info: QAPISourceInfo, tag: str) -> None:
                 raise QAPISemError(
                     info, "duplicated '%s' section" % tag)
             self.since = section
-        if tag != 'Since':
+        if tag not in ('Returns', 'Since'):
             self.sections.append(section)
         self.all_sections.append(section)
 
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index 716a9a4102..f2be711a2c 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -165,14 +165,14 @@  description starts on the same line
 remainder indented differently
     arg=arg3
 
+    section=Returns
+@Object
     feature=cmd-feat1
 a feature
     feature=cmd-feat2
 another feature
     section=Note
 @arg3 is undocumented
-    section=Returns
-@Object
     section=Errors
 some
     section=TODO
diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt
index 56d50d4992..fd88301431 100644
--- a/tests/qapi-schema/doc-good.txt
+++ b/tests/qapi-schema/doc-good.txt
@@ -184,6 +184,12 @@  Arguments
    Not documented
 
 
+Returns
+~~~~~~~
+
+"Object"
+
+
 Features
 ~~~~~~~~
 
@@ -200,12 +206,6 @@  Note
 "arg3" is undocumented
 
 
-Returns
-~~~~~~~
-
-"Object"
-
-
 Errors
 ~~~~~~
 
diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py
index 642daa29a4..1628efe0f3 100755
--- a/tests/qapi-schema/test-qapi.py
+++ b/tests/qapi-schema/test-qapi.py
@@ -127,6 +127,8 @@  def test_frontend(fname):
         print('    body=\n%s' % doc.body.text)
         for arg, section in doc.args.items():
             print('    arg=%s\n%s' % (arg, section.text))
+        if doc.returns:
+            print('    section=%s\n%s' % (doc.returns.tag, doc.returns.text))
         for feat, section in doc.features.items():
             print('    feature=%s\n%s' % (feat, section.text))
         for section in doc.sections: