@@ -655,13 +655,13 @@
# this to zero disables this function. This member is mutually
# exclusive with @reconnect. (default: 0) (Since: 9.2)
#
-# Only SocketAddress types 'unix', 'inet' and 'fd' are supported.
-#
# Features:
#
# @deprecated: Member @reconnect is deprecated. Use @reconnect-ms
# instead.
#
+# Only SocketAddress types 'unix', 'inet' and 'fd' are supported.
+#
# Since: 7.2
##
{ 'struct': 'NetdevStreamOptions',
@@ -195,12 +195,12 @@
#
# @typename: the type name of an object
#
+# Returns: a list of ObjectPropertyInfo 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 of ObjectPropertyInfo describing object properties
-#
# Since: 2.12
##
{ 'command': 'qom-list-properties',
@@ -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."
+ )
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))
@@ -157,12 +157,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
@@ -168,12 +168,12 @@ description starts on the same line
a feature
feature=cmd-feat2
another feature
- section=Detail
-.. note:: @arg3 is undocumented
section=Returns
@Object
section=Errors
some
+ section=Detail
+.. note:: @arg3 is undocumented
section=Todo
frobnicate
section=Detail
@@ -193,10 +193,6 @@ Features
"cmd-feat2"
another feature
-Note:
-
- "arg3" is undocumented
-
Returns
~~~~~~~
@@ -209,6 +205,10 @@ Errors
some
+Note:
+
+ "arg3" is undocumented
+
Notes:
* Lorem ipsum dolor sit amet
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> --- qapi/net.json | 4 ++-- qapi/qom.json | 4 ++-- scripts/qapi/parser.py | 16 ++++++++++++++++ tests/qapi-schema/doc-good.json | 4 ++-- tests/qapi-schema/doc-good.out | 4 ++-- tests/qapi-schema/doc-good.txt | 8 ++++---- 6 files changed, 28 insertions(+), 12 deletions(-)