[v3,32/63] qapi/parser: adjust info location for doc body section

Commit Message

John Snow March 11, 2025, 3:42 a.m. UTC

Instead of using the info object for the doc block as a whole (which
always points to the very first line of the block), update the info
pointer for each call to ensure_untagged_section when the existing
section is otherwise empty. This way, Sphinx error information will
match precisely to where the text actually starts.

For example, this patch will move the info pointer for the "Hello!"
untagged section ...

> ##       <-- from here ...
> # Hello! <-- ... to here.
> ##

This doesn't seem to improve error reporting now. It will with the
forthcoming QAPI doc transmogrifier.

If I stick bad rST into qapi/block-core.json like this:

>  ##
>  # @SnapshotInfo:
>  #
> +# rST syntax error: *ahh!
> +#
>  # @id: unique shapshot id
>  #
>  # @name: user chosen name

The existing code's error message will point to the beginning of the doc
comment, which is less than helpful. The transmogrifier's message will
point to the erroneous line, but to accomplish this, it needs this
patch.

Signed-off-by: John Snow <[e-mail]>
---
 scripts/qapi/parser.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

Comments

Markus Armbruster March 11, 2025, 7:01 a.m. UTC | #1

John Snow <[e-mail]> writes:

> Instead of using the info object for the doc block as a whole (which
> always points to the very first line of the block), update the info
> pointer for each call to ensure_untagged_section when the existing
> section is otherwise empty. This way, Sphinx error information will
> match precisely to where the text actually starts.
>
> For example, this patch will move the info pointer for the "Hello!"
> untagged section ...
>
>> ##       <-- from here ...
>> # Hello! <-- ... to here.
>> ##
>
> This doesn't seem to improve error reporting now. It will with the
> forthcoming QAPI doc transmogrifier.
>
> If I stick bad rST into qapi/block-core.json like this:
>
>>  ##
>>  # @SnapshotInfo:
>>  #
>> +# rST syntax error: *ahh!
>> +#
>>  # @id: unique shapshot id
>>  #
>>  # @name: user chosen name
>
> The existing code's error message will point to the beginning of the doc
> comment, which is less than helpful. The transmogrifier's message will
> point to the erroneous line, but to accomplish this, it needs this
> patch.
>
> Signed-off-by: John Snow <[e-mail]>
> ---
>  scripts/qapi/parser.py | 6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)
>
> diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
> index 64f0bb824ae..97def9f0e4f 100644
> --- a/scripts/qapi/parser.py
> +++ b/scripts/qapi/parser.py
> @@ -686,7 +686,11 @@ def end(self) -> None:
>      def ensure_untagged_section(self, info: QAPISourceInfo) -> None:
>          if self.all_sections and not self.all_sections[-1].tag:
>              # extend current section
> -            self.all_sections[-1].text += '\n'
> +            section = self.all_sections[-1]
> +            if not section.text:
> +                # Section is empty so far; update info to start *here*.
> +                section.info = info
> +            section.text += '\n'
>              return
>          # start new section
>          section = self.Section(info)

Reviewed-by: Markus Armbruster <[e-mail]>

Patch

diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 64f0bb824ae..97def9f0e4f 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -686,7 +686,11 @@  def end(self) -> None:
     def ensure_untagged_section(self, info: QAPISourceInfo) -> None:
         if self.all_sections and not self.all_sections[-1].tag:
             # extend current section
-            self.all_sections[-1].text += '\n'
+            section = self.all_sections[-1]
+            if not section.text:
+                # Section is empty so far; update info to start *here*.
+                section.info = info
+            section.text += '\n'
             return
         # start new section
         section = self.Section(info)