qapi: Improve error message for empty doc sections

Improve the message for an empty tagged section from

    empty doc section 'Note'

to

    text required after 'Note:'

and the message for an empty argument or feature description from

    empty doc section 'foo'

to

    text required after '@foo:'

Improve the error position to refer to the beginning of the empty
section instead of its end.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240216145841.2099240-8-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
This commit is contained in:
Markus Armbruster 2024-02-16 15:58:31 +01:00
parent bf00dc19f3
commit 573e2223f9
3 changed files with 10 additions and 10 deletions

View File

@ -239,8 +239,8 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
seen_item = False seen_item = False
dlnode = nodes.definition_list() dlnode = nodes.definition_list()
for section in doc.features.values(): for section in doc.features.values():
dlnode += self._make_dlitem([nodes.literal('', section.name)], dlnode += self._make_dlitem(
section.text) [nodes.literal('', section.member.name)], section.text)
seen_item = True seen_item = True
if not seen_item: if not seen_item:

View File

@ -476,9 +476,9 @@ class QAPIDoc:
self.info = parser.info self.info = parser.info
# parser, for error messages about indentation # parser, for error messages about indentation
self._parser = parser self._parser = parser
# optional section name (argument/member or section name) # section tag, if any ('Returns', '@name', ...)
self.name = name self.name = name
# section text without section name # section text without tag
self.text = '' self.text = ''
# indentation to strip (None means indeterminate) # indentation to strip (None means indeterminate)
self._indent = None if self.name else 0 self._indent = None if self.name else 0
@ -700,7 +700,7 @@ class QAPIDoc:
raise QAPIParseError(self._parser, raise QAPIParseError(self._parser,
"'%s' parameter name duplicated" % name) "'%s' parameter name duplicated" % name)
assert not self.sections assert not self.sections
new_section = QAPIDoc.ArgSection(self._parser, name) new_section = QAPIDoc.ArgSection(self._parser, '@' + name)
self._switch_section(new_section) self._switch_section(new_section)
symbols_dict[name] = new_section symbols_dict[name] = new_section
@ -727,9 +727,9 @@ class QAPIDoc:
# We do not create anonymous sections unless there is # We do not create anonymous sections unless there is
# something to put in them; this is a parser bug. # something to put in them; this is a parser bug.
assert self._section.name assert self._section.name
raise QAPIParseError( raise QAPISemError(
self._parser, self._section.info,
"empty doc section '%s'" % self._section.name) "text required after '%s:'" % self._section.name)
self._section = new_section self._section = new_section
@ -748,7 +748,7 @@ class QAPIDoc:
"%s '%s' lacks documentation" "%s '%s' lacks documentation"
% (member.role, member.name)) % (member.role, member.name))
self.args[member.name] = QAPIDoc.ArgSection(self._parser, self.args[member.name] = QAPIDoc.ArgSection(self._parser,
member.name) '@' + member.name)
self.args[member.name].connect(member) self.args[member.name].connect(member)
def connect_feature(self, feature: 'QAPISchemaFeature') -> None: def connect_feature(self, feature: 'QAPISchemaFeature') -> None:

View File

@ -1 +1 @@
doc-empty-section.json:7:1: empty doc section 'Note' doc-empty-section.json:6: text required after 'Note:'