diff options
| -rw-r--r-- | docs/devel/qapi-code-gen.rst | 6 | ||||
| -rw-r--r-- | scripts/qapi/parser.py | 23 | ||||
| -rw-r--r-- | tests/qapi-schema/doc-good.json | 2 | ||||
| -rw-r--r-- | tests/qapi-schema/doc-good.out | 2 | ||||
| -rw-r--r-- | 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 ~~~~~ |