Re: [PATCH 28/42] qapi/parser: prohibit untagged sections between tagged sections

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> This is being done primarily to ensure consistency between the source
> documents and the final, rendered HTML output. Because
> member/feature/returns sections will always appear in a visually grouped
> element in the HTML output, prohibiting free paragraphs between those
> sections ensures ordering consistency between source and the final
> render.
>
> Additionally, prohibiting such "middle" text paragraphs allows us to
> classify all plain text sections as either "intro" or "detail"
> sections, because these sections must either appear before structured
> elements ("intro") or afterwards ("detail").
>
> This keeps the inlining algorithm simpler with fewer "splice" points
> when inlining multiple documentation blocks.
>
> Signed-off-by: John Snow <jsnow@redhat.com>

[...]

> diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
> index b2f77ffdd7a..c5d2b950a82 100644
> --- a/scripts/qapi/parser.py
> +++ b/scripts/qapi/parser.py
> @@ -500,6 +500,20 @@ def get_doc(self) -> 'QAPIDoc':
>              self.accept(False)
>              line = self.get_doc_line()
>              have_tagged = False
> +            no_more_tags = False
> +
> +            def _tag_check(what: str) -> None:
> +                if what in ('TODO', 'Since'):
> +                    return
> +
> +                if no_more_tags:
> +                    raise QAPIParseError(
> +                        self,
> +                        f"{what!r} section cannot appear after free "
> +                        "paragraphs that follow other tagged sections. "
> +                        "Move this section upwards with the preceding "
> +                        "tagged sections."
> +                    )

Negative test case(s), please.

>  
>              while line is not None:
>                  # Blank lines
> @@ -513,6 +527,7 @@ def get_doc(self) -> 'QAPIDoc':
>                      if doc.features:
>                          raise QAPIParseError(
>                              self, "duplicated 'Features:' line")
> +                    _tag_check("Features")
>                      self.accept(False)
>                      line = self.get_doc_line()
>                      while line == '':
> @@ -576,6 +591,7 @@ def get_doc(self) -> 'QAPIDoc':
>                          )
>                          raise QAPIParseError(self, emsg)
>  
> +                    _tag_check(match.group(1))
>                      doc.new_tagged_section(
>                          self.info,
>                          QAPIDoc.Kind.from_string(match.group(1))

[...]