[07/16] qapi: Improve error message for empty doc sections

Commit Message

Markus Armbruster Feb. 16, 2024, 2:58 p.m. UTC

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 <[e-mail]>
---
 docs/sphinx/qapidoc.py                  |  4 ++--
 scripts/qapi/parser.py                  | 14 +++++++-------
 tests/qapi-schema/doc-empty-section.err |  2 +-
 3 files changed, 10 insertions(+), 10 deletions(-)

Comments

Daniel P. Berrangé Feb. 20, 2024, 3:16 p.m. UTC | #1

On Fri, Feb 16, 2024 at 03:58:31PM +0100, Markus Armbruster wrote:
> 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 <[e-mail]>
> ---
>  docs/sphinx/qapidoc.py                  |  4 ++--
>  scripts/qapi/parser.py                  | 14 +++++++-------
>  tests/qapi-schema/doc-empty-section.err |  2 +-
>  3 files changed, 10 insertions(+), 10 deletions(-)

Reviewed-by: Daniel P. Berrangé <[e-mail]>


With regards,
Daniel

Patch

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 488de23d72..1e8b4a70a1 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -239,8 +239,8 @@  def _nodes_for_features(self, doc):
         seen_item = False
         dlnode = nodes.definition_list()
         for section in doc.features.values():
-            dlnode += self._make_dlitem([nodes.literal('', section.name)],
-                                        section.text)
+            dlnode += self._make_dlitem(
+                [nodes.literal('', section.member.name)], section.text)
             seen_item = True
 
         if not seen_item:
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index a771013959..43daf55860 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -476,9 +476,9 @@  def __init__(self, parser: QAPISchemaParser,
             self.info = parser.info
             # parser, for error messages about indentation
             self._parser = parser
-            # optional section name (argument/member or section name)
+            # section tag, if any ('Returns', '@name', ...)
             self.name = name
-            # section text without section name
+            # section text without tag
             self.text = ''
             # indentation to strip (None means indeterminate)
             self._indent = None if self.name else 0
@@ -700,7 +700,7 @@  def _start_symbol_section(
             raise QAPIParseError(self._parser,
                                  "'%s' parameter name duplicated" % name)
         assert not self.sections
-        new_section = QAPIDoc.ArgSection(self._parser, name)
+        new_section = QAPIDoc.ArgSection(self._parser, '@' + name)
         self._switch_section(new_section)
         symbols_dict[name] = new_section
 
@@ -727,9 +727,9 @@  def _switch_section(self, new_section: 'QAPIDoc.Section') -> None:
             # We do not create anonymous sections unless there is
             # something to put in them; this is a parser bug.
             assert self._section.name
-            raise QAPIParseError(
-                self._parser,
-                "empty doc section '%s'" % self._section.name)
+            raise QAPISemError(
+                self._section.info,
+                "text required after '%s:'" % self._section.name)
 
         self._section = new_section
 
@@ -748,7 +748,7 @@  def connect_member(self, member: 'QAPISchemaMember') -> None:
                                    "%s '%s' lacks documentation"
                                    % (member.role, member.name))
             self.args[member.name] = QAPIDoc.ArgSection(self._parser,
-                                                        member.name)
+                                                        '@' + member.name)
         self.args[member.name].connect(member)
 
     def connect_feature(self, feature: 'QAPISchemaFeature') -> None:
diff --git a/tests/qapi-schema/doc-empty-section.err b/tests/qapi-schema/doc-empty-section.err
index ba7ba70125..5f03a6d733 100644
--- a/tests/qapi-schema/doc-empty-section.err
+++ b/tests/qapi-schema/doc-empty-section.err
@@ -1 +1 @@ 
-doc-empty-section.json:7:1: empty doc section 'Note'
+doc-empty-section.json:6: text required after 'Note:'