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::
# 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.
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))
# 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
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(
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: