motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-07-27 04:13:53 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

qapi: New documentation section tag "Errors"

Browse source 
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>
This commit is contained in:
Markus Armbruster 2024-02-27 12:39:11 +01:00
parent 51e97c14fb
commit 3a025d3d1f
5 changed files with 32 additions and 7 deletions
Download patch file Download diff file Expand all files Collapse all files

23
scripts/qapi/parser.py
View file

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