This patch prohibits plain documentation sections from appearing between
"tagged" sections. The two existing uses of this pattern are patched
out.
This is being done primarily to ensure consistency between the source
documents and the final, rendered HTML output. Because
member/feature/returns/error sections will always appear in a visually
grouped element in the HTML output, prohibiting plain 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 "details" sections,
because these sections must either appear before structured/tagged
sections ("intro") or afterwards ("details").
This keeps the inlining algorithm simpler with fewer "splice" points
when merging multiple documentation blocks.
Signed-off-by: John Snow <[email protected]>
---
qapi/qom.json | 4 ++--
scripts/qapi/parser.py | 17 +++++++++++++++++
tests/qapi-schema/doc-good.json | 4 ++--
tests/qapi-schema/doc-good.out | 4 ++--
tests/qapi-schema/doc-good.txt | 8 ++++----
5 files changed, 27 insertions(+), 10 deletions(-)
diff --git a/qapi/qom.json b/qapi/qom.json
index c653248f85d..1b47abd44e9 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -243,12 +243,12 @@
#
# @typename: the type name of an object
#
+# Returns: a list describing object properties
+#
# .. note:: Objects can create properties at runtime, for example to
# describe links between different devices and/or objects. These
# properties are not included in the output of this command.
#
-# Returns: a list describing object properties
-#
# Since: 2.12
##
{ 'command': 'qom-list-properties',
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index da0ac32ad89..dea056df30d 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -545,6 +545,19 @@ 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}' section cannot appear after plain "
+ "paragraphs that follow other tagged sections\n"
+ "Move this section up above the plain paragraph(s)."
+ )
while line is not None:
# Blank lines
@@ -558,6 +571,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 == '':
@@ -621,6 +635,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))
@@ -632,6 +647,8 @@ def get_doc(self) -> 'QAPIDoc':
have_tagged = True
else:
# plain paragraph
+ if have_tagged:
+ no_more_tags = True
# Paragraphs before tagged sections are "intro" paragraphs.
# Any appearing after are "detail" paragraphs.
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index fac13425b72..9103fed472e 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -165,12 +165,12 @@
# @cmd-feat1: a feature
# @cmd-feat2: another feature
#
-# .. note:: @arg3 is undocumented
-#
# Returns: @Object
#
# Errors: some
#
+# .. note:: @arg3 is undocumented
+#
# TODO: frobnicate
#
# .. admonition:: Notes
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index 04e29e8d50f..6a0167ad580 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -175,12 +175,12 @@ description starts on the same line
a feature
feature=cmd-feat2
another feature
- section=Details
-.. note:: @arg3 is undocumented
section=Returns
@Object
section=Errors
some
+ section=Details
+.. note:: @arg3 is undocumented
section=Todo
frobnicate
section=Details
diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt
index 74b73681d32..ded699dd596 100644
--- a/tests/qapi-schema/doc-good.txt
+++ b/tests/qapi-schema/doc-good.txt
@@ -120,16 +120,16 @@ Command cmd (Since: 2.10)
* **cmd-feat2** -- another feature
- Note:
-
- "arg3" is undocumented
-
Return:
"Object" -- "Object"
Errors:
some
+ Note:
+
+ "arg3" is undocumented
+
Notes:
* Lorem ipsum dolor sit amet
--
2.53.0
