From 3a025d3d1ffa63903aba7775a1061b0e30da4d13 Mon Sep 17 00:00:00 2001
From: Markus Armbruster <armbru@redhat.com>
Date: Tue, 27 Feb 2024 12:39:11 +0100
Subject: [PATCH] qapi: New documentation section tag "Errors"

We use section "Returns" for documenting both success and error
response of commands.

I intend to generate better command success response documentation.
Easier when "Returns" documents just he success response.

Create new section tag "Errors".  The next two commits will move error
response documentation from "Returns" sections to "Errors" sections.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240227113921.236097-4-armbru@redhat.com>
---
 docs/devel/qapi-code-gen.rst    |  6 +++++-
 scripts/qapi/parser.py          | 23 +++++++++++++++++------
 tests/qapi-schema/doc-good.json |  2 ++
 tests/qapi-schema/doc-good.out  |  2 ++
 tests/qapi-schema/doc-good.txt  |  6 ++++++
 5 files changed, 32 insertions(+), 7 deletions(-)

diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index 6804a4b596..f453bd3546 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -996,7 +996,8 @@ line "Features:", like this::
 
 A tagged section begins with a paragraph that starts with one of the
 following words: "Note:"/"Notes:", "Since:", "Example:"/"Examples:",
-"Returns:", "TODO:".  It ends with the start of a new section.
+"Returns:", "Errors:", "TODO:".  It ends with the start of a new
+section.
 
 The second and subsequent lines of tagged sections must be indented
 like this::
@@ -1007,6 +1008,9 @@ like this::
  #     Duis aute irure dolor in reprehenderit in voluptate velit esse
  #     cillum dolore eu fugiat nulla pariatur.
 
+"Returns" and "Errors" sections are only valid for commands.  They
+document the success and the error response, respectively.
+
 A "Since: x.y.z" tagged section lists the release that introduced the
 definition.
 
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index e4c2259e39..a32b2c7e7f 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -543,7 +543,7 @@ class QAPISchemaParser:
                         line = self.get_doc_indented(doc)
                     no_more_args = True
                 elif match := re.match(
-                        r'(Returns|Since|Notes?|Examples?|TODO): *',
+                        r'(Returns|Errors|Since|Notes?|Examples?|TODO): *',
                         line):
                     # tagged section
                     doc.new_tagged_section(self.info, match.group(1))
@@ -639,8 +639,9 @@ class QAPIDoc:
         # dicts mapping parameter/feature names to their description
         self.args: Dict[str, QAPIDoc.ArgSection] = {}
         self.features: Dict[str, QAPIDoc.ArgSection] = {}
-        # a command's "Returns" section
+        # a command's "Returns" and "Errors" section
         self.returns: Optional[QAPIDoc.Section] = None
+        self.errors: Optional[QAPIDoc.Section] = None
         # "Since" section
         self.since: Optional[QAPIDoc.Section] = None
         # sections other than .body, .args, .features
@@ -670,6 +671,11 @@ class QAPIDoc:
                 raise QAPISemError(
                     info, "duplicated '%s' section" % tag)
             self.returns = section
+        elif tag == 'Errors':
+            if self.errors:
+                raise QAPISemError(
+                    info, "duplicated '%s' section" % tag)
+            self.errors = section
         elif tag == 'Since':
             if self.since:
                 raise QAPISemError(
@@ -715,10 +721,15 @@ class QAPIDoc:
         self.features[feature.name].connect(feature)
 
     def check_expr(self, expr: QAPIExpression) -> None:
-        if self.returns and 'command' not in expr:
-            raise QAPISemError(
-                self.returns.info,
-                "'Returns' section is only valid for commands")
+        if 'command' not in expr:
+            if self.returns:
+                raise QAPISemError(
+                    self.returns.info,
+                    "'Returns' section is only valid for commands")
+            if self.errors:
+                raise QAPISemError(
+                    self.returns.info,
+                    "'Errors' section is only valid for commands")
 
     def check(self) -> None:
 
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index 5bb2b69071..de38a386e8 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -159,6 +159,8 @@
 #
 # Returns: @Object
 #
+# Errors: some
+#
 # TODO: frobnicate
 #
 # Notes:
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index 34ee74af4b..716a9a4102 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -173,6 +173,8 @@ another feature
 @arg3 is undocumented
     section=Returns
 @Object
+    section=Errors
+some
     section=TODO
 frobnicate
     section=Notes
diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt
index 879f6ff50a..847db70412 100644
--- a/tests/qapi-schema/doc-good.txt
+++ b/tests/qapi-schema/doc-good.txt
@@ -206,6 +206,12 @@ Returns
 "Object"
 
 
+Errors
+~~~~~~
+
+some
+
+
 Notes
 ~~~~~