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

QEMU-Devel Archive mirror
 help / color / mirror / Atom feed

From: Markus Armbruster <armbru@redhat.com>
To: qemu-devel@nongnu.org
Cc: richard.henderson@linaro.org
Subject: [PATCH 3/7] qapi: make returns sections special WIP
Date: Mon,  6 May 2024 13:02:46 +0200	[thread overview]
Message-ID: <20240506110254.3965097-7-armbru@redhat.com> (raw)
In-Reply-To: <20240506110254.3965097-1-armbru@redhat.com>

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(-)

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:
-- 
2.44.0

next prev parent reply	other threads:[~2024-05-06 11:07 UTC|newest]

Thread overview: 25+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2024-05-06 11:02 [PULL 0/7] QAPI patches patches for 2024-05-06 Markus Armbruster
2024-05-06 11:02 ` [PULL 1/7] qapi: New QAPISchemaBranches, QAPISchemaAlternatives Markus Armbruster
2024-05-06 11:02 ` [PATCH 1/7] qapi: make since sections special WIP Markus Armbruster
2024-05-06 11:44   ` Philippe Mathieu-Daudé
2024-05-06 12:48     ` Markus Armbruster
2024-05-06 12:45   ` Markus Armbruster
2024-05-06 11:02 ` [PULL 2/7] qapi: Rename visitor parameter @variants to @branches Markus Armbruster
2024-05-06 11:02 ` [PATCH 2/7] sphinx/qapidoc: Tweak "Since" section formatting WIP Markus Armbruster
2024-05-06 12:45   ` Markus Armbruster
2024-05-06 11:02 ` [PULL 3/7] qapi: Rename visitor parameter @variants to @alternatives Markus Armbruster
2024-05-06 11:02 ` Markus Armbruster [this message]
2024-05-06 12:46   ` [PATCH 3/7] qapi: make returns sections special WIP Markus Armbruster
2024-05-06 11:02 ` [PULL 4/7] qapi: Rename QAPISchemaObjectType.variants to .branches Markus Armbruster
2024-05-06 11:02 ` [PATCH 4/7] qapidoc: Generate default Returns WIP Markus Armbruster
2024-05-06 12:46   ` Markus Armbruster
2024-05-06 11:02 ` [PATCH 5/7] qapi: Drop "Returns" section where default is fine WIP Markus Armbruster
2024-05-06 12:46   ` Markus Armbruster
2024-05-06 11:02 ` [PULL 5/7] qapi: Rename QAPISchemaAlternateType.variants to .alternatives Markus Armbruster
2024-05-06 11:02 ` [PULL 6/7] qapi: Move conditional code from QAPISchemaVariants to its subtypes Markus Armbruster
2024-05-06 11:02 ` [PATCH 6/7] qga/qapi-schema: Drop "Returns" section where default is fine WIP Markus Armbruster
2024-05-06 12:47   ` Markus Armbruster
2024-05-06 11:02 ` [PATCH 7/7] find untagged sections WIP Markus Armbruster
2024-05-06 12:47   ` Markus Armbruster
2024-05-06 11:02 ` [PULL 7/7] qapi: Simplify QAPISchemaVariants @tag_member Markus Armbruster
2024-05-06 19:58 ` [PULL 0/7] QAPI patches patches for 2024-05-06 Richard Henderson

find likely ancestor, descendant, or conflicting patches for this message:
dfblob:f19f5ded7 dfblob:0237d13da dfblob:716a9a410 dfblob:56d50d499
dfblob:642daa29a dfblob:24bf1d9a9 dfblob:e8a482c37 dfblob:f2be711a2
dfblob:fd8830143 dfblob:1628efe0f
	(help)

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20240506110254.3965097-7-armbru@redhat.com \
    --to=armbru@redhat.com \
    --cc=qemu-devel@nongnu.org \
    --cc=richard.henderson@linaro.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Be sure your reply has a Subject: header at the top and a blank line before the message body.

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).