John Snow <[email protected]> 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 <[email protected]>
[...]
> 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))
[...]
