qapi: enforce section ordering
cover qapi: enforce section ordering
This is RFC quality and mostly meant for Markus to review, but if you're curious about what we're up to, you're welcome to nose around :)
It's a hackish application of enforcing a strict source section ordering in QAPIDoc and the accompanying patches that mend the source to respect that order. The point of the series is to, ultimately, make it easier to "inject" auto-generated documentation by enforcing a specific order to sections so that it is easier to insert documentation that is missing or can be implied from the source. A secondary goal is to more closely align the source documentation ordering with what gets rendered on the HTML documentation.
I am sending it to the list in this RFC state mostly to illustrate what each specific imposition requires in terms of source doc changes, and as a refresher for the specific restrictions I want to make to facilitate the inliner feature.
I am not neccessarily married to any specific technique/implementation for each specific restriction, but if it looks broadly OK to you (Markus), I can work on any requested polish or corollary cleanups. If you'd like to see a different approach, that's fine too. We may wish to discuss the ability to add notes/addendums to sections and what syntax would support that.
I had originally thought I'd work on the @oob project, but quickly remembered that my approach to that feature required yet-another place where we inject a doc section, and decided it would be best if I solved "where do we inject this autogenerated section?" once and for all, hence, you are getting this series first.
John Snow (8):
qapi: differentiate "intro" and "details" sections
qapi: prohibit 'details' sections between tagged sections
qapi: add "Details:" disambiguation marker
qapi: detect potentially semantically ambiguous intro paragraphs
qapi: re-order QAPI doc block sections
qapi: enforce doc block section ordering
qapi: re-order 'since' sections to always be last
qapi: enforce strict positioning for "Since:" section
docs/interop/firmware.json | 4 +- docs/interop/vhost-user.json | 3 +- docs/sphinx/qapidoc.py | 2 +- qapi/accelerator.json | 12 +-- qapi/acpi.json | 8 +- qapi/block-core.json | 183 ++++++++++++++++---------------- qapi/block-export.json | 20 ++-- qapi/block.json | 48 ++++----- qapi/char.json | 36 +++---- qapi/control.json | 14 +-- qapi/dump.json | 16 +-- qapi/machine-s390x.json | 16 +-- qapi/machine.json | 144 +++++++++++++------------ qapi/migration.json | 102 ++++++++++-------- qapi/misc-arm.json | 6 +- qapi/misc-i386.json | 40 ++++--- qapi/misc.json | 68 ++++++------ qapi/net.json | 42 ++++---- qapi/pci.json | 4 +- qapi/qdev.json | 12 +-- qapi/qom.json | 34 +++--- qapi/replay.json | 16 +-- qapi/rocker.json | 16 +-- qapi/run-state.json | 66 +++++++----- qapi/tpm.json | 12 +-- qapi/trace.json | 8 +- qapi/transaction.json | 4 +- qapi/ui.json | 76 +++++++------ qapi/vfio.json | 4 +- qapi/virtio.json | 46 ++++---- qapi/yank.json | 2 +- scripts/qapi/parser.py | 121 ++++++++++++++++++--- tests/qapi-schema/doc-good.json | 12 +-- tests/qapi-schema/doc-good.out | 10 +- tests/qapi-schema/doc-good.txt | 18 ++-- 35 files changed, 695 insertions(+), 530 deletions(-)
Signature · 1 line
2.53.0
PATCH 1/8 qapi: differentiate "intro" and "details" sections
This patch begins distinguishing "Plain" sections as being either "Intro" or "Details" sections for the purpose of knowing when/where/how to inline those sections.
The Intro section is always the first section of any doc block. It may be empty or any number of paragraphs. It is interrupted by any other non-plaintext section, i.e.; Members, Features, Errors, Returns, Since, and TODO.
The details section, when present, is either the last section or the second-to-last section when a "Since:" section is present. It consists of any plain text in the doc block that follows any named sections if present.
--- docs/sphinx/qapidoc.py | 2 +- scripts/qapi/parser.py | 35 +++++++++++++++++++++++----------- tests/qapi-schema/doc-good.out | 8 ++++---- 3 files changed, 29 insertions(+), 16 deletions(-)
docs/sphinx/qapidoc.py +1 -1
@@ -368,7 +368,7 @@ def visit_sections(self, ent: QAPISchemaDefinition) -> None: for i, section in enumerate(sections): section.text = self.reformat_arobase(section.text) - if section.kind == QAPIDoc.Kind.PLAIN: + if section.kind.name in ("INTRO", "DETAILS"): self.visit_paragraph(section) elif section.kind == QAPIDoc.Kind.MEMBER: assert isinstance(section, QAPIDoc.ArgSection)
scripts/qapi/parser.py +24 -11
@@ -544,7 +544,7 @@ def get_doc(self) -> 'QAPIDoc': doc = QAPIDoc(info, symbol) self.accept(False) line = self.get_doc_line() - no_more_args = False + have_tagged = False while line is not None: # Blank lines
@@ -573,10 +573,10 @@ def get_doc(self) -> 'QAPIDoc': if not doc.features: raise QAPIParseError( self, 'feature descriptions expected') - no_more_args = True + have_tagged = True elif match := self._match_at_name_colon(line): # description - if no_more_args: + if have_tagged: raise QAPIParseError( self, "description of '@%s:' follows a section"
@@ -588,7 +588,7 @@ def get_doc(self) -> 'QAPIDoc': if text: doc.append_line(text) line = self.get_doc_indented(doc) - no_more_args = True + have_tagged = True elif match := re.match( r'(Returns|Errors|Since|Notes?|Examples?|TODO)' r'(?!::): *',
@@ -629,10 +629,14 @@ def get_doc(self) -> 'QAPIDoc': if text: doc.append_line(text) line = self.get_doc_indented(doc) - no_more_args = True + have_tagged = True else: # plain paragraph - doc.ensure_untagged_section(self.info) + + # Paragraphs before tagged sections are "intro" paragraphs. + # Any appearing after are "detail" paragraphs. + intro = not have_tagged + doc.ensure_untagged_section(self.info, intro) doc.append_line(line) line = self.get_doc_paragraph(doc) else:
@@ -674,13 +678,14 @@ class QAPIDoc: """ class Kind(enum.Enum): - PLAIN = 0 + INTRO = 0 MEMBER = 1 FEATURE = 2 RETURNS = 3 ERRORS = 4 SINCE = 5 TODO = 6 + DETAILS = 7 @staticmethod def from_string(kind: str) -> 'QAPIDoc.Kind':
@@ -730,7 +735,7 @@ def __init__(self, info: QAPISourceInfo, symbol: Optional[str] = None): self.symbol: Optional[str] = symbol # the sections in textual order self.all_sections: List[QAPIDoc.Section] = [ - QAPIDoc.Section(info, QAPIDoc.Kind.PLAIN) + QAPIDoc.Section(info, QAPIDoc.Kind.INTRO) ] # the body section self.body: Optional[QAPIDoc.Section] = self.all_sections[0]
@@ -748,12 +753,20 @@ def __init__(self, info: QAPISourceInfo, symbol: Optional[str] = None): def end(self) -> None: for section in self.all_sections: section.text = section.text.strip('\n') - if section.kind != QAPIDoc.Kind.PLAIN and section.text == '': + if ( + section.kind not in ( + QAPIDoc.Kind.INTRO, QAPIDoc.Kind.DETAILS + ) and section.text == '' + ): raise QAPISemError( section.info, "text required after '%s:'" % section.kind) - def ensure_untagged_section(self, info: QAPISourceInfo) -> None: - kind = QAPIDoc.Kind.PLAIN + def ensure_untagged_section( + self, + info: QAPISourceInfo, + intro: bool = True, + ) -> None: + kind = QAPIDoc.Kind.INTRO if intro else QAPIDoc.Kind.DETAILS if self.all_sections and self.all_sections[-1].kind == kind: # extend current section
tests/qapi-schema/doc-good.out +4 -4
@@ -116,7 +116,7 @@ The _one_ {and only}, description on the same line Also _one_ {and only} feature=enum-member-feat a member feature - section=Plain + section=Details @two is undocumented doc symbol=Base body=
@@ -175,7 +175,7 @@ description starts on the same line a feature feature=cmd-feat2 another feature - section=Plain + section=Details .. note:: @arg3 is undocumented section=Returns @Object
@@ -183,7 +183,7 @@ another feature some section=Todo frobnicate - section=Plain + section=Details .. admonition:: Notes - Lorem ipsum dolor sit amet
@@ -216,7 +216,7 @@ If you're bored enough to read this, go see a video of boxed cats a feature feature=cmd-feat2 another feature - section=Plain + section=Details .. qmp-example:: -> "this example"
Signature · 1 line
2.53.0
Re: [PATCH 1/8] qapi: differentiate "intro" and "details" sections
Quoted 9 lines · John Snow
This patch begins distinguishing "Plain" sections as being either "Intro" or "Details" sections for the purpose of knowing when/where/how to inline those sections.
The Intro section is always the first section of any doc block. It may be empty or any number of paragraphs. It is interrupted by any other non-plaintext section, i.e.; Members, Features, Errors, Returns, Since, and TODO.
Quoted 6 lines
The details section, when present, is either the last section or the second-to-last section when a "Since:" section is present. It consists of any plain text in the doc block that follows any named sections if present.
Signed-off-by John Snow <[email protected]>
The commit message explains what kinds INTRO and DETAILS are, but not why they're useful. My guess:
1. Represent the future "Details:" marker: the plain section before it is of kind INTRO, the one afterwards is of kind DETAILS.
2. Future programming convenience? With just PLAIN, code may have to understand the section's context to make decisions, and with INTRO and DETAILS is doesn't.
Guess close enough?
The commit message covers PLAIN sections at the beginning and at the end (modulo Since:). It doesn't cover PLAIN sections between tagged sections / member descriptions. You disallow these in PATCH 2. You can either cover them here, or get rid of them by swapping PATCH 1 and 2.
Hmm, is your description of DETAILS accurate? Looks like it isn't; see my review of tests/qapi-schema/doc-good.out below.
Quoted 5 lines
--- docs/sphinx/qapidoc.py | 2 +- scripts/qapi/parser.py | 35 +++++++++++++++++++++++----------- tests/qapi-schema/doc-good.out | 8 ++++---- 3 files changed, 29 insertions(+), 16 deletions(-)
[Skipping the Python code in my first pass...]
tests/qapi-schema/doc-good.out The _one_ {and only}, description on the same line · line 120
Quoted 11 lines
tests/qapi-schema/doc-good.out +1
-1@@ -116,7 +116,7 @@ The _one_ {and only}, description on the same line Also _one_ {and only} feature=enum-member-feat a member feature - section=Plain + section=Details @two is undocumented
The section containing "@two is undocumented" changes from PLAIN to DETAILS. Doc source:
##
# @Enum:
#
# @one: The _one_ {and only}, description on the same line
#
# Features:
# @enum-feat: Also _one_ {and only}
# @enum-member-feat: a member feature
#
# @two is undocumented
##It is at the end. Good.
tests/qapi-schema/doc-good.out description starts on the same line · line 179
Quoted 9 lines
tests/qapi-schema/doc-good.out +1
-1doc symbol=Base body=@@ -175,7 +175,7 @@ description starts on the same line a feature feature=cmd-feat2 another feature - section=Plain + section=Details .. note:: @arg3 is undocumented
The section containing "@arg3 is undocumented" changes from PLAIN to DETAILS. Doc source:
Doc source:
##
# @cmd:
#
# @arg1:
# description starts on a new line,
# indented
#
# @arg2: description starts on the same line
# remainder indented differently
#
# Returns: @Object
#
# Errors: some
#
# Features:
# @cmd-feat1: a feature
# @cmd-feat2: another feature
#
# .. note:: @arg3 is undocumented
#
# TODO: frobnicate
#It is *not* at the end. Is the commit message inaccurate?
tests/qapi-schema/doc-good.out another feature · line 189
Quoted 11 lines
tests/qapi-schema/doc-good.out +1
-1section=Returns @Object@@ -183,7 +183,7 @@ another feature some section=Todo frobnicate - section=Plain + section=Details .. admonition:: Notes - Lorem ipsum dolor sit amet
- Ut enim ad minim veniam
[some section body text elided for brevity...]
Note::
Ceci n'est pas une note
section=Since
2.10
The section starting with the adminition and ending after "Ceci n'est pas une note" changes from PLAIN to DETAILS. Doc source continued:
# .. admonition:: Notes
#
# - Lorem ipsum dolor sit amet
# - Ut enim ad minim veniam
#
[same text elided...]
#
# Note::
# Ceci n'est pas une note
#
# Since: 2.10
##It is second-to-last, and the last section is SINCE. Good.
tests/qapi-schema/doc-good.out If you're bored enough to read this, go see a video of boxed cats · line 222
Quoted 9 lines
tests/qapi-schema/doc-good.out +1
-1@@ -216,7 +216,7 @@ If you're bored enough to read this, go see a video of boxed cats a feature featurec=md-feat2 another feature - section=Plain + section=Details .. qmp-example:: -> "this example"
This one is also at the end. Good.
Re: [PATCH 1/8] qapi: differentiate "intro" and "details" sections
Quoted 16 lines · Markus Armbruster
Quoted 14 lines · John Snow
This patch begins distinguishing "Plain" sections as being either "Intro" or "Details" sections for the purpose of knowing when/where/how to inline those sections.
The Intro section is always the first section of any doc block. It may be empty or any number of paragraphs. It is interrupted by any other non-plaintext section, i.e.; Members, Features, Errors, Returns, Since, and TODO.
The details section, when present, is either the last section or the second-to-last section when a "Since:" section is present. It consists of any plain text in the doc block that follows any named sections if present.
Quoted 5 lines
Quoted 1 line
Signed-off-by John Snow <[email protected]>The commit message explains what kinds INTRO and DETAILS are, but not why they're useful. My guess:
Right, my apologies. Leaning on you having some existing knowledge here, and also going light on details because the series is still obviously in flux.
Let me elaborate on the motivations here...
Quoted 3 lines
1. Represent the future "Details:" marker: the plain section before it is of kind INTRO, the one afterwards is of kind DETAILS.
Yes.
Quoted 6 lines
2. Future programming convenience? With just PLAIN, code may have to understand the section's context to make decisions, and with INTRO and DETAILS is doesn't.
Guess close enough?
Pretty much.
Originally, I thought I'd inline things like this:
Intro (child)
Intro (parent)
...other sections...
Details (parent)
Details (child)
Last time we went over this, you mused that there was likely never a sufficient reason to actually inline the intro. I recall believing and accepting this.
So functionally what this does for us is:
(1) Explicitly delineate what comes before the tabular section of the docs (members, Returns, Errors, features) and what comes after.
(2) Explicitly defines what will not be inlined.
Quoted 5 lines
The commit message covers PLAIN sections at the beginning and at the end (modulo Since:). It doesn't cover PLAIN sections between tagged sections / member descriptions. You disallow these in PATCH 2. You can either cover them here, or get rid of them by swapping PATCH 1 and 2.
Sure. For now they're separated just to separate concerns in review, but if you believe both should be all-at-once, that's fine too. I think there's not a regression by separating it, though. It's just a semantic change from details meaning "anything after the intro" to "specifically the closing section". The intermediate meaning exists for only one patch.
Quoted 3 lines
Hmm, is your description of DETAILS accurate? Looks like it isn't; see my review of tests/qapi-schema/doc-good.out below.
Whoops, future-think. It winds up being true, but isn't true yet as of this commit. Well, almost. See below.
Quoted 76 lines
Quoted 5 lines
--- docs/sphinx/qapidoc.py | 2 +- scripts/qapi/parser.py | 35 +++++++++++++++++++++++----------- tests/qapi-schema/doc-good.out | 8 ++++---- 3 files changed, 29 insertions(+), 16 deletions(-)[Skipping the Python code in my first pass...]
Review
Quoted 1 line
(quoted diff) +0
-0b/tests/qapi-schema/doc-good.out
tests/qapi-schema/doc-good.out The _one_ {and only}, description on the same line · line 120
Quoted 10 lines
index
04a55072646..04e29e8d50f100644tests/qapi-schema/doc-good.out +1
-1@@ -116,7 +116,7 @@ The _one_ {and only}, description on the same line Also _one_ {and only} feature=enum-member-feat a member feature - section=Plain + section=Details @two is undocumentedThe section containing "@two is undocumented" changes from PLAIN to DETAILS. Doc source:
## # @Enum: # # @one: The _one_ {and only}, description on the same line # # Features: # @enum-feat: Also _one_ {and only} # @enum-member-feat: a member feature # # @two is undocumented ##It is at the end. Good.
tests/qapi-schema/doc-good.out description starts on the same line · line 179
Quoted 9 lines
tests/qapi-schema/doc-good.out +1
-1doc symbol=Base body=@@ -175,7 +175,7 @@ description starts on the same line a feature feature=cmd-feat2 another feature - section=Plain + section=Details .. note:: @arg3 is undocumentedThe section containing "@arg3 is undocumented" changes from PLAIN to DETAILS. Doc source:
Doc source:
## # @cmd: # # @arg1: # description starts on a new line, # indented # # @arg2: description starts on the same line # remainder indented differently # # Returns: @Object # # Errors: some # # Features: # @cmd-feat1: a feature # @cmd-feat2: another feature # # .. note:: @arg3 is undocumented # # TODO: frobnicate #
Quoted 2 lines
It is *not* at the end. Is the commit message inaccurate?
Ah. I wasn't considering TODO... Since it is a comment I mentally elided it.
What I mean to say is that Details is (will be) essentially the last content section that is actually rendered.
In the HTML, it will always be last if present because both TODO and Since are actually entirely removed from the flow of the document.
Though as we both point out, what i write is not technically true here. (It can currently be an intermediate section AND Since is not the only section that may follow it.)
Quoted 52 lines
tests/qapi-schema/doc-good.out another feature · line 189
Quoted 11 lines
tests/qapi-schema/doc-good.out +1
-1section=Returns @Object@@ -183,7 +183,7 @@ another feature some section=Todo frobnicate - section=Plain + section=Details .. admonition:: Notes - Lorem ipsum dolor sit amet- Ut enim ad minim veniam
[some section body text elided for brevity...]
Note:: Ceci n'est pas une note section=Since 2.10The section starting with the adminition and ending after "Ceci n'est pas une note" changes from PLAIN to DETAILS. Doc source continued:
# .. admonition:: Notes # # - Lorem ipsum dolor sit amet # - Ut enim ad minim veniam # [same text elided...] # # Note:: # Ceci n'est pas une note # # Since: 2.10 ##It is second-to-last, and the last section is SINCE. Good.
tests/qapi-schema/doc-good.out If you're bored enough to read this, go see a video
Quoted 1 line
tests/qapi-schema/doc-good.out +0
-0@@ -216,7 +216,7 @@ If you're bored enough to read this, go see a videoof boxed cats
tests/qapi-schema/doc-good.out If you're bored enough to read this, go see a video of boxed cats · line 222
Quoted 8 lines
tests/qapi-schema/doc-good.out +1
-1a feature featurec=md-feat2 another feature - section=Plain + section=Details .. qmp-example:: -> "this example"This one is also at the end. Good.
Re: [PATCH 1/8] qapi: differentiate "intro" and "details" sections
Quoted 20 lines · John Snow
Quoted 18 lines · Markus Armbruster
Quoted 15 lines · John Snow
This patch begins distinguishing "Plain" sections as being either "Intro" or "Details" sections for the purpose of knowing when/where/how to inline those sections.
The Intro section is always the first section of any doc block. It may be empty or any number of paragraphs. It is interrupted by any other non-plaintext section, i.e.; Members, Features, Errors, Returns, Since, and TODO.
The details section, when present, is either the last section or the second-to-last section when a "Since:" section is present. It consists of any plain text in the doc block that follows any named sections if present.
Signed-off-by John Snow <[email protected]>
Quoted 7 lines
Quoted 3 lines
The commit message explains what kinds INTRO and DETAILS are, but not why they're useful. My guess:
Right, my apologies. Leaning on you having some existing knowledge here, and also going light on details because the series is still obviously in flux.
No worries!
Quoted 27 lines
Let me elaborate on the motivations here...
Quoted 3 lines
1. Represent the future "Details:" marker: the plain section before it is of kind INTRO, the one afterwards is of kind DETAILS.
Yes.
Quoted 6 lines
2. Future programming convenience? With just PLAIN, code may have to understand the section's context to make decisions, and with INTRO and DETAILS is doesn't.
Guess close enough?
Pretty much.
Originally, I thought I'd inline things like this:
Intro (child)
Intro (parent)
...other sections...
Details (parent)
Details (child)
Quoted 3 lines
Last time we went over this, you mused that there was likely never a sufficient reason to actually inline the intro. I recall believing and accepting this.
Turns out we use the first section (i.e. INTRO) for describing the thing being defined. Inlining such descriptions results in nonsense. For instance, here's SevGuestProperties and its base SevGuestProperties:
##
# @SevCommonProperties:
#
# Properties common to objects that are derivatives of sev-common.
#
[...]
##
# @SevGuestProperties:
#
# Properties for sev-guest objects.
#
# @dh-cert-file: guest owners DH certificate (encoded with base64)
#
[...]Inlining the base as you originally thought would result in something like
Object SevGuestProperties (Since: 2.12)
Properties for sev-guest objects.
Properties common to objects that are derivatives of sev-common.
Members: * dh-cert-file (string, optional) -- guest owners DH certificate (encoded with base64)
The intro paragraph inlined from the base is nonsense.
We either stop writing such descriptions (ugh), or we drop them on inlining. If we drop, code needs to recognize them. The only method I can see is to assume INTRO is description.
Now, the QAPI generator cannot stop people from putting stuff in INTRO is *not* description and *should* be inlined. This is a risk we will have to accept to gain the benefits of inlining.
For the inliner's initial merge, we'll want to review all the INTRO sections the inliner drops. If almost all of them are fine, the risk is low.
Quoted 6 lines
So functionally what this does for us is:
(1) Explicitly delineate what comes before the tabular section of the docs (members, Returns, Errors, features) and what comes after.
(2) Explicitly defines what will not be inlined.
Yes.
I think we'll want to at least hint at this in the final commit message. The full story would be too much, I guess.
Quoted 11 lines
Quoted 5 lines
The commit message covers PLAIN sections at the beginning and at the end (modulo Since:). It doesn't cover PLAIN sections between tagged sections / member descriptions. You disallow these in PATCH 2. You can either cover them here, or get rid of them by swapping PATCH 1 and 2.
Sure. For now they're separated just to separate concerns in review, but if you believe both should be all-at-once, that's fine too. I think there's not a regression by separating it, though. It's just a semantic change from details meaning "anything after the intro" to "specifically the closing section". The intermediate meaning exists for only one patch.
Have you tried swapping the patches?
If that's bothersome, squashing them together may well do.
Quoted 87 lines
Quoted 3 lines
Hmm, is your description of DETAILS accurate? Looks like it isn't; see my review of tests/qapi-schema/doc-good.out below.
Whoops, future-think. It winds up being true, but isn't true yet as of this commit. Well, almost. See below.
Quoted 76 lines
Quoted 5 lines
--- docs/sphinx/qapidoc.py | 2 +- scripts/qapi/parser.py | 35 +++++++++++++++++++++++----------- tests/qapi-schema/doc-good.out | 8 ++++---- 3 files changed, 29 insertions(+), 16 deletions(-)[Skipping the Python code in my first pass...]
Review
Quoted 1 line
(quoted diff) +0
-0b/tests/qapi-schema/doc-good.out
tests/qapi-schema/doc-good.out The _one_ {and only}, description on the same line · line 120
Quoted 10 lines
index
04a55072646..04e29e8d50f100644tests/qapi-schema/doc-good.out +1
-1@@ -116,7 +116,7 @@ The _one_ {and only}, description on the same line Also _one_ {and only} feature=enum-member-feat a member feature - section=Plain + section=Details @two is undocumentedThe section containing "@two is undocumented" changes from PLAIN to DETAILS. Doc source:
## # @Enum: # # @one: The _one_ {and only}, description on the same line # # Features: # @enum-feat: Also _one_ {and only} # @enum-member-feat: a member feature # # @two is undocumented ##It is at the end. Good.
tests/qapi-schema/doc-good.out description starts on the same line · line 179
Quoted 9 lines
tests/qapi-schema/doc-good.out +1
-1doc symbol=Base body=@@ -175,7 +175,7 @@ description starts on the same line a feature feature=cmd-feat2 another feature - section=Plain + section=Details .. note:: @arg3 is undocumentedThe section containing "@arg3 is undocumented" changes from PLAIN to DETAILS. Doc source:
Doc source:
## # @cmd: # # @arg1: # description starts on a new line, # indented # # @arg2: description starts on the same line # remainder indented differently # # Returns: @Object # # Errors: some # # Features: # @cmd-feat1: a feature # @cmd-feat2: another feature # # .. note:: @arg3 is undocumented # # TODO: frobnicate #Quoted 2 lines
It is *not* at the end. Is the commit message inaccurate?
Quoted 7 lines
Ah. I wasn't considering TODO... Since it is a comment I mentally elided it.
What I mean to say is that Details is (will be) essentially the last content section that is actually rendered.
In the HTML, it will always be last if present because both TODO and Since are actually entirely removed from the flow of the document.
We can handwave these two away, but the issue persists until the next patch.
Consider this change to the test before the series:
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index fac13425b7..4d586b043f 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -169,6 +169,8 @@
#
# Returns: @Object
#
+# plain in the middle
+#
# Errors: some
#
# TODO: frobnicate
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index 04a5507264..040e901474 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -179,6 +179,8 @@ another feature
.. note:: @arg3 is undocumented
section=Returns
@Object
+ section=Plain
+plain in the middle
section=Errors
some
section=TodoThe current patch then acquires another hunk:
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 04e29e8d50..28abb1d98e 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -179,6 +179,8 @@ another feature
.. note:: @arg3 is undocumented
section=Returns
@Object
+ section=Details
+plain in the middle
section=Errors
some
section=Todo
Quoted 3 lines
Though as we both point out, what i write is not technically true here. (It can currently be an intermediate section AND Since is not the only section that may follow it.)
[...]
PATCH 2/8 qapi: prohibit 'details' sections between tagged sections
In reply to John SnowThis 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.
--- 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(-)
qapi/qom.json +2 -2
@@ -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',
scripts/qapi/parser.py +17 -0
@@ -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.
tests/qapi-schema/doc-good.json +2 -2
@@ -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
tests/qapi-schema/doc-good.out +2 -2
@@ -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
tests/qapi-schema/doc-good.txt +4 -4
@@ -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
Signature · 1 line
2.53.0
Re: [PATCH 2/8] qapi: prohibit 'details' sections between tagged sections
Quoted 3 lines · John Snow
This patch prohibits plain documentation sections from appearing between "tagged" sections. The two existing uses of this pattern are patched out.
One real use, and one just for test coverage.
Quoted 6 lines
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.
Is consistency an actual problem being fixed, or a future problem being avoided? I'm guessing the latter, based on my review of qom.json below.
Quoted 4 lines
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").
Huh?
The previous patch already classified all plain text sections as either INTRO or DETAILS.
I think the paragraph would make sense if this patch came before the previous one.
Quoted 21 lines
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(-)qapi/qom.json +1
-0@@ -243,12 +243,12 @@ # # @typename: the type name of an object # +# Returns: a list describing object properties
qapi/qom.json line 254
Quoted 10 lines
qapi/qom.json +1
-2+# # .. 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',
Rendered documentation before the patch:
Command qom-list-properties (Since: 2.12)
List properties associated with a QOM object.
Arguments:
* typename (string) -- the type name of an object
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.
Return:
[ObjectPropertyInfo] -- a list describing object properties
Afterwards:
Command qom-list-properties (Since: 2.12)
List properties associated with a QOM object.
Arguments:
* typename (string) -- the type name of an object
Return:
[ObjectPropertyInfo] -- 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.
Fine.
[Skipping the Python code in my first pass...]
Quoted 28 lines
tests/qapi-schema/doc-good.json +2
-2@@ -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:: Notestests/qapi-schema/doc-good.out +0
-1@@ -175,12 +175,12 @@ description starts on the same line a feature feature=cmd-feat2 another feature - section=Details
tests/qapi-schema/doc-good.out description starts on the same line · line 186
Quoted 10 lines
tests/qapi-schema/doc-good.out +2
-1-.. note:: @arg3 is undocumented section=Returns @Object section=Errors some + section=Details +.. note:: @arg3 is undocumented section=Todo frobnicate section=Details
The Details section is still between tagged sections. The code prohibiting it must have a hole :)
Quoted 25 lines
tests/qapi-schema/doc-good.txt +4
-4@@ -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
Re: [PATCH 2/8] qapi: prohibit 'details' sections between tagged sections
Quoted 15 lines · Markus Armbruster
Quoted 3 lines · John Snow
This patch prohibits plain documentation sections from appearing between "tagged" sections. The two existing uses of this pattern are patched out.
One real use, and one just for test coverage.
Quoted 6 lines
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.
Quoted 3 lines
Is consistency an actual problem being fixed, or a future problem being avoided? I'm guessing the latter, based on my review of qom.json below.
With just one actual use, it's *mostly* avoiding future problems. It does correct one instance in the rendered HTML of a plain text paragraph interrupting the tabular fields, which is not a "bug" per se but a visual inconsistency I wish to eliminate.
The problem is minimal now, but intensifies when considering inlining. Prohibiting the insertion of any section into the "tabular region" helps ensure consistent, good looking HTML manual output.
A goal is for source order to match rendered order. Rendered order looks best with all tabular elements grouped together without root-level paragraphs interrupting them.
Thus, the desire to restrict source order.
(i.e. we allow only one intro section and only one details section.)
Quoted 5 lines
Quoted 4 lines
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").
Quoted 8 lines
Huh?
The previous patch already classified all plain text sections as either INTRO or DETAILS.
I think the paragraph would make sense if this patch came before the previous one.
Mmm.
The previous patch is confusingly worded and I didn't do better here.
Previous patch categorizes all plaintext sections as intro or details, but technically allows multiple details sections.
This patch enforces that we only have one.
(...I think. Currently not clear on how TODO and Since behave with this logic. Maybe we end up with multiple details sections interrupted only by non-rendered sections... Edit: yes, you find such a case below.)
Quoted 107 lines
Quoted 21 lines
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(-)qapi/qom.json +1
-0@@ -243,12 +243,12 @@ # # @typename: the type name of an object # +# Returns: a list describing object propertiesqapi/qom.json line 254
Quoted 10 lines
qapi/qom.json +1
-2+# # .. 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',Rendered documentation before the patch:
Command qom-list-properties (Since: 2.12)
List properties associated with a QOM object.
Arguments:
* typename (string) -- the type name of an objectNote:
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.
Return:
[ObjectPropertyInfo] -- a list describing object propertiesAfterwards:
Command qom-list-properties (Since: 2.12)
List properties associated with a QOM object.
Arguments:
* typename (string) -- the type name of an objectReturn:
[ObjectPropertyInfo] -- a list describing object propertiesNote:
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.
Fine.
[Skipping the Python code in my first pass...]
Review
Quoted 1 line
(quoted diff) +0
-0
b/tests/qapi-schema/doc-good.jsonReview
Quoted 19 lines
index
fac13425b72..9103fed472e100644tests/qapi-schema/doc-good.json +2
-2@@ -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(quoted diff) +0
-0b/tests/qapi-schema/doc-good.out
Quoted 13 lines
index
04e29e8d50f..6a0167ad580100644tests/qapi-schema/doc-good.out +0
-2@@ -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
Quoted 9 lines
tests/qapi-schema/doc-good.out description starts on the same line · line 186
Quoted 5 lines
tests/qapi-schema/doc-good.out +2
-0+ section=Details +.. note:: @arg3 is undocumented section=Todo frobnicate section=DetailsThe Details section is still between tagged sections. The code prohibiting it must have a hole :)
Well, there's the answer to my above self-musing on Since/TODO... After reading my replies, is it clear what I am concerned with accomplishing?
If not, the goal for *rendered output* is this:
1. Intro (literally and truly only ever one section, both in the QAPIDoc sense and in the rendered HTML output sense)
2. All tabular sections (members, returns, Errors, features)
3. Details
You'll notice I didn't bother specifying Since and TODO here. TODO is removed from rendered output, so I don't actually care where it goes in the QAPIDoc source list.
Since is also removed from the flow in the HTML output, so I also don't care about it. (However, you requested that it specifically go last, so I do address that in this series and later prohibit any details sections from appearing after a Since marker.)
The true "semantic" goals here are two things:
(1) Prohibiting free text from appearing within the tabular section region
(2) Delineating free text that appears before the tabular region from free text that appears after it.
I apologize for conflating "section order" with "rendered section order".
You are right to point out that these sections i do not care about may, in the source, impact the classification of other sections and the total number thereof.
(i.e. TODO is enough to terminate the intro without an explicit details marker, and Since/TODO can create multiple details sections after the tabular region. They are merged visually but not in the QAPIDoc sections list. I don't consider this a bug per se, but it is the source of a lot of confusion here in this series when I am eliding that technicality.)
Quoted 28 lines
Review
Quoted 1 line
(quoted diff) +0
-0
b/tests/qapi-schema/doc-good.txtQuoted 24 lines
index
74b73681d32..ded699dd596100644tests/qapi-schema/doc-good.txt +4
-4@@ -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
Re: [PATCH 2/8] qapi: prohibit 'details' sections between tagged sections
Quoted 17 lines · John Snow
Quoted 15 lines · Markus Armbruster
Quoted 3 lines · John Snow
This patch prohibits plain documentation sections from appearing between "tagged" sections. The two existing uses of this pattern are patched out.
One real use, and one just for test coverage.
Quoted 6 lines
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.
Quoted 8 lines
Quoted 3 lines
Is consistency an actual problem being fixed, or a future problem being avoided? I'm guessing the latter, based on my review of qom.json below.
With just one actual use, it's *mostly* avoiding future problems. It does correct one instance in the rendered HTML of a plain text paragraph interrupting the tabular fields, which is not a "bug" per se but a visual inconsistency I wish to eliminate.
A visual blemish you wish to eliminate is not an inconsistency between doc source and rendered doc.
It would become one if you made the generator move the PLAIN section out to fix the blemish, but that's not the plan.
Instead, you fix the blemish by making doc writers move their PLAIN sections out.
Quoted 1 line
The problem is minimal now, but intensifies when considering inlining.
Would inlining make it necessary for the generator to move PLAIN sections around? Why?
If yes, this patch eliminates a visual blemish now *and* avoids inconsistency later.
Quoted 10 lines
Prohibiting the insertion of any section into the "tabular region" helps ensure consistent, good looking HTML manual output.
A goal is for source order to match rendered order. Rendered order looks best with all tabular elements grouped together without root-level paragraphs interrupting them.
Thus, the desire to restrict source order.
(i.e. we allow only one intro section and only one details section.)
I'm not opposed to that, I just want a clearer commit message :)
Quoted 156 lines
Quoted 5 lines
Quoted 4 lines
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").
Quoted 8 lines
Huh?
The previous patch already classified all plain text sections as either INTRO or DETAILS.
I think the paragraph would make sense if this patch came before the previous one.
Mmm.
The previous patch is confusingly worded and I didn't do better here.
Previous patch categorizes all plaintext sections as intro or details, but technically allows multiple details sections.
This patch enforces that we only have one.
(...I think. Currently not clear on how TODO and Since behave with this logic. Maybe we end up with multiple details sections interrupted only by non-rendered sections... Edit: yes, you find such a case below.)
Quoted 105 lines
Quoted 21 lines
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(-)qapi/qom.json +1
-0@@ -243,12 +243,12 @@ # # @typename: the type name of an object # +# Returns: a list describing object propertiesqapi/qom.json line 254
Quoted 10 lines
qapi/qom.json +1
-2+# # .. 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',Rendered documentation before the patch:
Command qom-list-properties (Since: 2.12)
List properties associated with a QOM object.
Arguments:
* typename (string) -- the type name of an objectNote:
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.
Return:
[ObjectPropertyInfo] -- a list describing object propertiesAfterwards:
Command qom-list-properties (Since: 2.12)
List properties associated with a QOM object.
Arguments:
* typename (string) -- the type name of an objectReturn:
[ObjectPropertyInfo] -- a list describing object propertiesNote:
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.
Fine.
[Skipping the Python code in my first pass...]
Quoted 33 lines
tests/qapi-schema/doc-good.json +2
-2@@ -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:: Notestests/qapi-schema/doc-good.out +0
-2@@ -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 someQuoted 9 lines
tests/qapi-schema/doc-good.out description starts on the same line · line 186
Quoted 5 lines
tests/qapi-schema/doc-good.out +2
-0+ section=Details +.. note:: @arg3 is undocumented section=Todo frobnicate section=DetailsThe Details section is still between tagged sections. The code prohibiting it must have a hole :)
Well, there's the answer to my above self-musing on Since/TODO... After reading my replies, is it clear what I am concerned with accomplishing?
If not, the goal for *rendered output* is this:
1. Intro (literally and truly only ever one section, both in the QAPIDoc sense and in the rendered HTML output sense)
2. All tabular sections (members, returns, Errors, features)
3. Details
Quoted 8 lines
You'll notice I didn't bother specifying Since and TODO here. TODO is removed from rendered output, so I don't actually care where it goes in the QAPIDoc source list.
Since is also removed from the flow in the HTML output, so I also don't care about it. (However, you requested that it specifically go last, so I do address that in this series and later prohibit any details sections from appearing after a Since marker.)
Understood.
Quoted 13 lines
The true "semantic" goals here are two things:
(1) Prohibiting free text from appearing within the tabular section region
(2) Delineating free text that appears before the tabular region from free text that appears after it.
I apologize for conflating "section order" with "rendered section order".
You are right to point out that these sections i do not care about may, in the source, impact the classification of other sections and the total number thereof.
Quoted 5 lines
(i.e. TODO is enough to terminate the intro without an explicit details marker, and Since/TODO can create multiple details sections after the tabular region. They are merged visually but not in the QAPIDoc sections list. I don't consider this a bug per se, but it is the source of a lot of confusion here in this series when I am eliding that technicality.)
A commit message needs to explain why and how the patch is useful. When details distract from the core argument too much, it can be beneficial to gloss over them.
Glossing over is not the same as not mentioning.
Commit message readers use it to build a mental model of things. A good model simplifies reality. A bad model misleads about reality.
If the commit message completely elides details that matter, readers end up with bad models and unwarranted confidence in them. They'll then struggle with the patch.
If the commit message at least hints at the details elided, readers may still end up with bad models, but they'll hopefully understand their limitations, treat them as incomplete, and fill in the details from the patch.
[...]
Re: [PATCH 2/8] qapi: prohibit 'details' sections between tagged sections
In reply to John SnowQuoted 19 lines · John Snow
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.
Quoted 8 lines
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(-)
Missing: update to docs/devel/qapi-code-gen.rst. Suggest to put in a FIXME, so we don't forget.
Missing: negative test case for the new error.
Re: [PATCH 2/8] qapi: prohibit 'details' sections between tagged sections
Quoted 30 lines · Markus Armbruster
Quoted 19 lines · John Snow
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.
Quoted 8 lines
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(-)
Quoted 3 lines
Missing: update to
docs/devel/qapi-code-gen.rst. Suggest to put in a FIXME, so we don't forget.
I will add a FIXME.
Quoted 2 lines
Missing: negative test case for the new error.
I will add a FIXME here as well and implement the test once we agree on the approach, implementation, and wording.
Quoted 1 line
PATCH 3/8 qapi: add "Details:" disambiguation marker
In reply to John SnowWhen a documentation block consists only of plaintext, there is nothing to semantically differentiate the "intro" from the "details" section. For the purposes of the inliner, the intro section is likely to be dropped while the details section will be merged onto the end of the parent's details section.
When the delineation between "intro" and "details" is not clear because there is no intervening "members", "features", "errors", "returns", "TODO", or "Since" section, the parser assumes the entire text section is an "intro" section. This may not always be semantically true, so this patch clarifies certain sections explicitly as "details" sections by using an empty "Details:" marker.
--- qapi/block-core.json | 3 +++ qapi/machine.json | 2 +- qapi/migration.json | 8 ++++++-- qapi/net.json | 2 +- qapi/qom.json | 4 ++++ qapi/yank.json | 2 +- scripts/qapi/parser.py | 8 ++++++++ 7 files changed, 24 insertions(+), 5 deletions(-)
qapi/block-core.json +3 -0
@@ -5007,6 +5007,9 @@ # @blockdev-reopen: # # Reopens one or more block devices using the given set of options. +# +# Details: +# # Any option not specified will be reset to its default value # regardless of its previous status. If an option cannot be changed # or a particular driver does not support reopening then the command
qapi/machine.json +1 -1
@@ -1259,7 +1259,7 @@ # Return the amount of initially allocated and present hotpluggable # (if enabled) memory in bytes. # -# TODO: This line is a hack to separate the example from the body +# Details: # # .. qmp-example:: #
qapi/migration.json +6 -2
@@ -1633,7 +1633,7 @@ # # Query replication status while the vm is running. # -# TODO: This line is a hack to separate the example from the body +# Details: # # .. qmp-example:: #
@@ -1651,6 +1651,8 @@ # # Xen uses this command to notify replication to trigger a checkpoint. # +# Details: +# # .. qmp-example:: # # -> { "execute": "xen-colo-do-checkpoint" }
@@ -1687,7 +1689,7 @@ # # Query COLO status while the vm is running. # -# TODO: This line is a hack to separate the example from the body +# Details: # # .. qmp-example:: #
@@ -1724,6 +1726,8 @@ # # Pause a migration. Currently it only supports postcopy. # +# Details: +# # .. qmp-example:: # # -> { "execute": "migrate-pause" }
qapi/net.json +1 -1
@@ -1070,7 +1070,7 @@ # switches. This can be useful when network bonds fail-over the # active slave. # -# TODO: This line is a hack to separate the example from the body +# Details: # # .. qmp-example:: #
qapi/qom.json +4 -0
@@ -777,6 +777,8 @@ # # Properties for memory-backend-shm objects. # +# Details: +# # This memory backend supports only shared memory, which is the # default. #
@@ -792,6 +794,8 @@ # # Properties for memory-backend-epc objects. # +# Details: +# # The @merge boolean option is false by default with epc # # The @dump boolean option is false by default with epc
qapi/yank.json +1 -1
@@ -104,7 +104,7 @@ # # Query yank instances. See `YankInstance` for more information. # -# TODO: This line is a hack to separate the example from the body +# Details: # # .. qmp-example:: #
scripts/qapi/parser.py +8 -0
@@ -588,6 +588,14 @@ def _tag_check(what: str) -> None: raise QAPIParseError( self, 'feature descriptions expected') have_tagged = True + elif line == 'Details:': + _tag_check("Details") + self.accept(False) + line = self.get_doc_line() + while line == '': + self.accept(False) + line = self.get_doc_line() + have_tagged = True elif match := self._match_at_name_colon(line): # description if have_tagged:
Signature · 1 line
2.53.0
Re: [PATCH 3/8] qapi: add "Details:" disambiguation marker
Quoted 14 lines · John Snow
When a documentation block consists only of plaintext, there is nothing to semantically differentiate the "intro" from the "details" section. For the purposes of the inliner, the intro section is likely to be dropped while the details section will be merged onto the end of the parent's details section.
When the delineation between "intro" and "details" is not clear because there is no intervening "members", "features", "errors", "returns", "TODO", or "Since" section, the parser assumes the entire text section is an "intro" section. This may not always be semantically true, so this patch clarifies certain sections explicitly as "details" sections by using an empty "Details:" marker.
Signed-off-by John Snow <[email protected]>
Quoted 9 lines
--- qapi/block-core.json | 3 +++ qapi/machine.json | 2 +- qapi/migration.json | 8 ++++++-- qapi/net.json | 2 +- qapi/qom.json | 4 ++++ qapi/yank.json | 2 +- scripts/qapi/parser.py | 8 ++++++++ 7 files changed, 24 insertions(+), 5 deletions(-)
Missing: update to docs/devel/qapi-code-gen.rst. Suggest to put in a FIXME, so we don't forget.
Quoted 6 lines
qapi/block-core.json +0
-0
qapi/block-core.json line 5015
Quoted 9 lines
qapi/block-core.json +3
-0@@ -5007,6 +5007,9 @@ # @blockdev-reopen: # # Reopens one or more block devices using the given set of options. +# +# Details: +# # Any option not specified will be reset to its default value # regardless of its previous status. If an option cannot be changed # or a particular driver does not support reopening then the command
Rendered documentation before the patch:
Command blockdev-reopen (Since: 6.1)
Reopens one or more block devices using the given set of options. Any option not specified will be reset to its default value regardless of its previous status. If an option cannot be changed or a particular driver does not support reopening then the command will return an error. All devices in the list are reopened in one transaction, so if one of them fails then the whole transaction is cancelled.
[...]
Unlike with "blockdev-add", the "backing" option must always be present unless the node being reopened does not have a backing file and its image does not have a default backing file name as part of its metadata.
Arguments:
* options ([BlockdevOptions]) -- Not documented
The command's single argument is undocumented, and the doc generator papered over this (sadly common defect) by splicing in this "Not documented" description.
Aside: why not boxed, like blockdev-add? Design mistake?
The patch moves the splice point. Not wrong, but we should really fill in the document gap instead.
qapi/machine.json line 1262
Quoted 10 lines
qapi/machine.json +1
-1@@ -1259,7 +1259,7 @@ # Return the amount of initially allocated and present hotpluggable # (if enabled) memory in bytes. # -# TODO: This line is a hack to separate the example from the body +# Details:
This replaces a hack by a proper solution. More of the same below, not mentioning this again.
Quoted 17 lines
qapi/machine.json +0
-0# # .. qmp-example:: #qapi/migration.json +1
-1@@ -1633,7 +1633,7 @@ # # Query replication status while the vm is running. # -# TODO: This line is a hack to separate the example from the body +# Details: # # .. qmp-example:: #
qapi/migration.json line 1658
Quoted 8 lines
qapi/migration.json +2
-0@@ -1651,6 +1651,8 @@ # # Xen uses this command to notify replication to trigger a checkpoint. # +# Details: +# # .. qmp-example:: # # -> { "execute": "xen-colo-do-checkpoint" }
No change to generated documentation. I guess this is needed to avoid the yelping added in the next patch. Correct?
Quoted 10 lines
qapi/migration.json +1
-1@@ -1687,7 +1689,7 @@ # # Query COLO status while the vm is running. # -# TODO: This line is a hack to separate the example from the body +# Details: # # .. qmp-example:: #
qapi/migration.json line 1733
Quoted 8 lines
qapi/migration.json +2
-0@@ -1724,6 +1726,8 @@ # # Pause a migration. Currently it only supports postcopy. # +# Details: +# # .. qmp-example:: # # -> { "execute": "migrate-pause" }
Likewise?
Quoted 18 lines
qapi/net.json +1
-1@@ -1070,7 +1070,7 @@ # switches. This can be useful when network bonds fail-over the # active slave. # -# TODO: This line is a hack to separate the example from the body +# Details: # # .. qmp-example:: #qapi/qom.json +0
-0
qapi/qom.json line 784
Quoted 8 lines
qapi/qom.json +2
-0@@ -777,6 +777,8 @@ # # Properties for memory-backend-shm objects. # +# Details: +# # This memory backend supports only shared memory, which is the # default. #
Rendered documentation changes from
Object MemoryBackendShmProperties (Since: 9.1)
Availability: CONFIG_POSIX
Properties for memory-backend-shm objects.
This memory backend supports only shared memory, which is the default.
Members:
* The members of MemoryBackendProperties.
to
Object MemoryBackendShmProperties (Since: 9.1)
Availability: CONFIG_POSIX
Properties for memory-backend-shm objects.
Members:
* The members of MemoryBackendProperties.
This memory backend supports only shared memory, which is the default.
Feels like a wash.
I guess we need a "Details:" somewhere to avoid yelping. Correct?
qapi/qom.json line 801
Quoted 9 lines
qapi/qom.json +2
-0@@ -792,6 +794,8 @@ # # Properties for memory-backend-epc objects. # +# Details: +# # The @merge boolean option is false by default with epc # # The @dump boolean option is false by default with epc
Similar change to rendered documentation, same request to confirm yelping.
qapi/yank.json line 110
Quoted 13 lines
qapi/yank.json +1
-1@@ -104,7 +104,7 @@ # # Query yank instances. See `YankInstance` for more information. # -# TODO: This line is a hack to separate the example from the body +# Details: # # .. qmp-example:: #
[Skipping the Python code in my first pass...]
I'd be tempted to split the patch into hack replacement and yelping avoidance.
Re: [PATCH 3/8] qapi: add "Details:" disambiguation marker
Quoted 26 lines · Markus Armbruster
Quoted 14 lines · John Snow
When a documentation block consists only of plaintext, there is nothing to semantically differentiate the "intro" from the "details" section. For the purposes of the inliner, the intro section is likely to be dropped while the details section will be merged onto the end of the parent's details section.
When the delineation between "intro" and "details" is not clear because there is no intervening "members", "features", "errors", "returns", "TODO", or "Since" section, the parser assumes the entire text section is an "intro" section. This may not always be semantically true, so this patch clarifies certain sections explicitly as "details" sections by using an empty "Details:" marker.
Signed-off-by John Snow <[email protected]>Quoted 9 lines
--- qapi/block-core.json | 3 +++ qapi/machine.json | 2 +- qapi/migration.json | 8 ++++++-- qapi/net.json | 2 +- qapi/qom.json | 4 ++++ qapi/yank.json | 2 +- scripts/qapi/parser.py | 8 ++++++++ 7 files changed, 24 insertions(+), 5 deletions(-)
Quoted 3 lines
Missing: update to
docs/devel/qapi-code-gen.rst. Suggest to put in a FIXME, so we don't forget.
ACK
Quoted 38 lines
Quoted 6 lines
qapi/block-core.json +0
-0qapi/block-core.json line 5015
Quoted 9 lines
qapi/block-core.json +3
-0@@ -5007,6 +5007,9 @@ # @blockdev-reopen: # # Reopens one or more block devices using the given set of options. +# +# Details: +# # Any option not specified will be reset to its default value # regardless of its previous status. If an option cannot be changed # or a particular driver does not support reopening then the commandRendered documentation before the patch:
Command blockdev-reopen (Since: 6.1)
Reopens one or more block devices using the given set of options. Any option not specified will be reset to its default value regardless of its previous status. If an option cannot be changed or a particular driver does not support reopening then the command will return an error. All devices in the list are reopened in one transaction, so if one of them fails then the whole transaction is cancelled.
[...]
Unlike with "blockdev-add", the "backing" option must always be present unless the node being reopened does not have a backing file and its image does not have a default backing file name as part of its metadata.
Arguments:
* options ([BlockdevOptions]) -- Not documented
Quoted 9 lines
The command's single argument is undocumented, and the doc generator papered over this (sadly common defect) by splicing in this "Not documented" description.
Aside: why not boxed, like blockdev-add? Design mistake?
The patch moves the splice point. Not wrong, but we should really fill in the document gap instead.
Sure, but I'm worried about other things for the time being. I don't disagree but I think I'm the wrong person for intricate doc cleanup work of that sort.
Quoted 34 lines
qapi/machine.json line 1262
Quoted 10 lines
qapi/machine.json +1
-1@@ -1259,7 +1259,7 @@ # Return the amount of initially allocated and present hotpluggable # (if enabled) memory in bytes. # -# TODO: This line is a hack to separate the example from the body +# Details:This replaces a hack by a proper solution. More of the same below, not mentioning this again.
Quoted 20 lines
qapi/machine.json +0
-0# # .. qmp-example:: #qapi/migration.json +1
-1@@ -1633,7 +1633,7 @@ # # Query replication status while the vm is running. # -# TODO: This line is a hack to separate the example from the body +# Details: # # .. qmp-example:: #@@ -1651,6 +1651,8 @@ # # Xen uses this command to notify replication to trigger a checkpoint. #
Quoted 9 lines
qapi/migration.json line 1658
Quoted 5 lines
qapi/migration.json +2
-0+# Details: +# # .. qmp-example:: # # -> { "execute": "xen-colo-do-checkpoint" }No change to generated documentation. I guess this is needed to avoid the yelping added in the next patch. Correct?
Yes, probably. I didn't differentiate the cases...
Quoted 71 lines
Quoted 10 lines
qapi/migration.json +1
-1@@ -1687,7 +1689,7 @@ # # Query COLO status while the vm is running. # -# TODO: This line is a hack to separate the example from the body +# Details: # # .. qmp-example:: #qapi/migration.json line 1733
Quoted 8 lines
qapi/migration.json +2
-0@@ -1724,6 +1726,8 @@ # # Pause a migration. Currently it only supports postcopy. # +# Details: +# # .. qmp-example:: # # -> { "execute": "migrate-pause" }Likewise?
Quoted 18 lines
qapi/net.json +1
-1@@ -1070,7 +1070,7 @@ # switches. This can be useful when network bonds fail-over the # active slave. # -# TODO: This line is a hack to separate the example from the body +# Details: # # .. qmp-example:: #qapi/qom.json +0
-0qapi/qom.json line 784
Quoted 8 lines
qapi/qom.json +2
-0@@ -777,6 +777,8 @@ # # Properties for memory-backend-shm objects. # +# Details: +# # This memory backend supports only shared memory, which is the # default. #Rendered documentation changes from
Object MemoryBackendShmProperties (Since: 9.1)
Availability:CONFIG_POSIXProperties for memory-backend-shm objects.
This memory backend supports only shared memory, which is the default.
Members:
* The members of MemoryBackendProperties.to
Object MemoryBackendShmProperties (Since: 9.1)
Availability:CONFIG_POSIXProperties for memory-backend-shm objects.
Members:
* The members of MemoryBackendProperties.
Quoted 7 lines
This memory backend supports only shared memory, which is the default.
Feels like a wash.
I guess we need a "Details:" somewhere to avoid yelping. Correct?
If we choose to formally include the yelper patch. I included it to show all of the cases where this *might* make a difference.
There's likely other heuristics we could employ to reduce how often we yelp. For instance, things that are never inlined from, or never inline, could likely be skipped as it won't make a difference.
I think the trick here is to come up with a blanket "rule" that makes sense and is easy to understand for the uninitiated, even if that rule covers more cases than strictly necessary.
This patch used a very broad algorithm with almost no edge cases to yelp.
Concern: if I do not make the parser yelp, we may see new cases added in the future that render in unintended ways. If I make the yelper too yelpy, it's just annoying without providing sufficient benefit.
Truth is likely in the middle somewhere. This patch is an effort to find and flush out that truth by brute force.
Quoted 29 lines
qapi/qom.json line 801
Quoted 9 lines
qapi/qom.json +2
-0@@ -792,6 +794,8 @@ # # Properties for memory-backend-epc objects. # +# Details: +# # The @merge boolean option is false by default with epc # # The @dump boolean option is false by default with epcSimilar change to rendered documentation, same request to confirm yelping.
qapi/yank.json line 110
Quoted 13 lines
qapi/yank.json +1
-1@@ -104,7 +104,7 @@ # # Query yank instances. See `YankInstance` for more information. # -# TODO: This line is a hack to separate the example from the body +# Details: # # .. qmp-example:: #[Skipping the Python code in my first pass...]
Quoted 3 lines
I'd be tempted to split the patch into hack replacement and yelping avoidance.
ACK, I can do that. It will take a moment to audit which cause real html output changes and which are solely yelp avoidance, but it can be done.
Note that some changes may appear to be yelp avoidance only without the inliner active. Some cases *may* produce tangible differences with the inliner active.
I don't have an example at hand or a method currently to identify them, it's just a heads up for the possibility.
Quoted 1 line
Re: [PATCH 3/8] qapi: add "Details:" disambiguation marker
Quoted 79 lines · John Snow
Quoted 26 lines · Markus Armbruster
Quoted 14 lines · John Snow
When a documentation block consists only of plaintext, there is nothing to semantically differentiate the "intro" from the "details" section. For the purposes of the inliner, the intro section is likely to be dropped while the details section will be merged onto the end of the parent's details section.
When the delineation between "intro" and "details" is not clear because there is no intervening "members", "features", "errors", "returns", "TODO", or "Since" section, the parser assumes the entire text section is an "intro" section. This may not always be semantically true, so this patch clarifies certain sections explicitly as "details" sections by using an empty "Details:" marker.
Signed-off-by John Snow <[email protected]>Quoted 9 lines
--- qapi/block-core.json | 3 +++ qapi/machine.json | 2 +- qapi/migration.json | 8 ++++++-- qapi/net.json | 2 +- qapi/qom.json | 4 ++++ qapi/yank.json | 2 +- scripts/qapi/parser.py | 8 ++++++++ 7 files changed, 24 insertions(+), 5 deletions(-)Quoted 3 lines
Missing: update to
docs/devel/qapi-code-gen.rst. Suggest to put in a FIXME, so we don't forget.ACK
Quoted 44 lines
Quoted 6 lines
qapi/block-core.json +0
-0qapi/block-core.json line 5015
Quoted 9 lines
qapi/block-core.json +3
-0@@ -5007,6 +5007,9 @@ # @blockdev-reopen: # # Reopens one or more block devices using the given set of options. +# +# Details: +# # Any option not specified will be reset to its default value # regardless of its previous status. If an option cannot be changed # or a particular driver does not support reopening then the commandRendered documentation before the patch:
Command blockdev-reopen (Since: 6.1)
Reopens one or more block devices using the given set of options. Any option not specified will be reset to its default value regardless of its previous status. If an option cannot be changed or a particular driver does not support reopening then the command will return an error. All devices in the list are reopened in one transaction, so if one of them fails then the whole transaction is cancelled.
[...]
Unlike with "blockdev-add", the "backing" option must always be present unless the node being reopened does not have a backing file and its image does not have a default backing file name as part of its metadata.
Arguments:
* options ([BlockdevOptions]) -- Not documentedThe command's single argument is undocumented, and the doc generator papered over this (sadly common defect) by splicing in this "Not documented" description.
Aside: why not boxed, like blockdev-add? Design mistake?
Quoted 7 lines
Quoted 3 lines
The patch moves the splice point. Not wrong, but we should really fill in the document gap instead.
Sure, but I'm worried about other things for the time being. I don't disagree but I think I'm the wrong person for intricate doc cleanup work of that sort.
Put in a TODO for now?
Quoted 129 lines
Quoted 34 lines
qapi/machine.json line 1262
Quoted 10 lines
qapi/machine.json +1
-1@@ -1259,7 +1259,7 @@ # Return the amount of initially allocated and present hotpluggable # (if enabled) memory in bytes. # -# TODO: This line is a hack to separate the example from the body +# Details:This replaces a hack by a proper solution. More of the same below, not mentioning this again.
Quoted 20 lines
qapi/machine.json +0
-0# # .. qmp-example:: #qapi/migration.json +1
-1@@ -1633,7 +1633,7 @@ # # Query replication status while the vm is running. # -# TODO: This line is a hack to separate the example from the body +# Details: # # .. qmp-example:: #@@ -1651,6 +1651,8 @@ # # Xen uses this command to notify replication to trigger a checkpoint. #Quoted 9 lines
qapi/migration.json line 1658
Quoted 5 lines
qapi/migration.json +2
-0+# Details: +# # .. qmp-example:: # # -> { "execute": "xen-colo-do-checkpoint" }No change to generated documentation. I guess this is needed to avoid the yelping added in the next patch. Correct?
Yes, probably. I didn't differentiate the cases...
Quoted 71 lines
Quoted 10 lines
qapi/migration.json +1
-1@@ -1687,7 +1689,7 @@ # # Query COLO status while the vm is running. # -# TODO: This line is a hack to separate the example from the body +# Details: # # .. qmp-example:: #qapi/migration.json line 1733
Quoted 8 lines
qapi/migration.json +2
-0@@ -1724,6 +1726,8 @@ # # Pause a migration. Currently it only supports postcopy. # +# Details: +# # .. qmp-example:: # # -> { "execute": "migrate-pause" }Likewise?
Quoted 18 lines
qapi/net.json +1
-1@@ -1070,7 +1070,7 @@ # switches. This can be useful when network bonds fail-over the # active slave. # -# TODO: This line is a hack to separate the example from the body +# Details: # # .. qmp-example:: #qapi/qom.json +0
-0qapi/qom.json line 784
Quoted 8 lines
qapi/qom.json +2
-0@@ -777,6 +777,8 @@ # # Properties for memory-backend-shm objects. # +# Details: +# # This memory backend supports only shared memory, which is the # default. #Rendered documentation changes from
Object MemoryBackendShmProperties (Since: 9.1)
Availability:CONFIG_POSIXProperties for memory-backend-shm objects.
This memory backend supports only shared memory, which is the default.
Members:
* The members of MemoryBackendProperties.to
Object MemoryBackendShmProperties (Since: 9.1)
Availability:CONFIG_POSIXProperties for memory-backend-shm objects.
Members:
* The members of MemoryBackendProperties.Quoted 7 lines
This memory backend supports only shared memory, which is the default.
Feels like a wash.
I guess we need a "Details:" somewhere to avoid yelping. Correct?
If we choose to formally include the yelper patch. I included it to show all of the cases where this *might* make a difference.
Quoted 7 lines
There's likely other heuristics we could employ to reduce how often we yelp. For instance, things that are never inlined from, or never inline, could likely be skipped as it won't make a difference.
I think the trick here is to come up with a blanket "rule" that makes sense and is easy to understand for the uninitiated, even if that rule covers more cases than strictly necessary.
Yes.
I think it's better to keep the rules around "Details:" as simple as possible, even if that means we have to write it more often. The decision whether and where to write it should be as obvious as we can make it. The less obvious is it, the more often we'll get it wrong[*].
Quoted 5 lines
This patch used a very broad algorithm with almost no edge cases to yelp.
Concern: if I do not make the parser yelp, we may see new cases added in the future that render in unintended ways. If I make the yelper too yelpy, it's just annoying without providing sufficient benefit.
Yes, this is still an open problem.
Quoted 2 lines
Truth is likely in the middle somewhere. This patch is an effort to find and flush out that truth by brute force.
Good.
Quoted 29 lines
Quoted 29 lines
qapi/qom.json line 801
Quoted 9 lines
qapi/qom.json +2
-0@@ -792,6 +794,8 @@ # # Properties for memory-backend-epc objects. # +# Details: +# # The @merge boolean option is false by default with epc # # The @dump boolean option is false by default with epcSimilar change to rendered documentation, same request to confirm yelping.
qapi/yank.json line 110
Quoted 13 lines
qapi/yank.json +1
-1@@ -104,7 +104,7 @@ # # Query yank instances. See `YankInstance` for more information. # -# TODO: This line is a hack to separate the example from the body +# Details: # # .. qmp-example:: #[Skipping the Python code in my first pass...]
Quoted 6 lines
Quoted 3 lines
I'd be tempted to split the patch into hack replacement and yelping avoidance.
ACK, I can do that. It will take a moment to audit which cause real html output changes and which are solely yelp avoidance, but it can be done.
Thanks!
Quoted 6 lines
Note that some changes may appear to be yelp avoidance only without the inliner active. Some cases *may* produce tangible differences with the inliner active.
I don't have an example at hand or a method currently to identify them, it's just a heads up for the possibility.
[*] A glance at rendered documentation should catch most instances of wrong, but in developers generally don't do that.
PATCH 4/8 qapi: detect potentially semantically ambiguous intro paragraphs
In reply to John SnowCajole the QAPI Doc parser into yelping if a QAPI Doc Block contains more than one paragraph of plaintext and has no instances of Members, Errors, Returns, or Features that would naturally delineate an introduction from additional details such as notes, examples, and additional details.
--- scripts/qapi/parser.py | 44 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+)
scripts/qapi/parser.py +44 -0
@@ -960,3 +960,47 @@ def check_args_section( check_args_section(self.args, 'member') check_args_section(self.features, 'feature') + + # Ignore free-form documentation sections + if self.symbol is None: + return + + n_intro_para = 0 + has_intro = False + has_other = False + + for section in self.all_sections: + # Ignore Since: and TODO: sections + if section.kind in (QAPIDoc.Kind.SINCE, QAPIDoc.Kind.TODO): + continue + + # Ignore empty plaintext sections + if section.kind in (QAPIDoc.Kind.INTRO, QAPIDoc.Kind.DETAILS): + if not section.text: + continue + + if section.kind == QAPIDoc.Kind.INTRO: + has_intro = True + n_intro_para = len(section.text.split("\n\n")) + elif not ( + section.kind == QAPIDoc.Kind.MEMBER and not section.text + ): + # This section is something other than an Intro section; + # but we explicitly exclude stub entries for members + # (undocumented fields with no text) from consideration + # because they were auto-generated; they are not useful + # for identifying the case "There are multiple intro + # paragraphs and no other explicit source sections." + has_other = True + + # If an intro section is only a single paragraph, we are + # confident it is well and truly just an introduction. If we + # have a single, multi-paragraph intro section and *no other* + # explicit sections in source code, it is potentially a semantic + # goof-em-up where the intro and details sections have bled + # together. Warn about this case. + if has_intro and n_intro_para > 1 and not has_other: + print( + f"Warning: paragraphs for {self.symbol} are ambiguous " + "and could be either intro or details paragraphs." + )
Signature · 1 line
2.53.0
Re: [PATCH 4/8] qapi: detect potentially semantically ambiguous intro paragraphs
Quoted 10 lines · John Snow
Cajole the QAPI Doc parser into yelping if a QAPI Doc Block contains more than one paragraph of plaintext and has no instances of Members, Errors, Returns, or Features that would naturally delineate an introduction from additional details such as notes, examples, and additional details.
Signed-off-by John Snow <[email protected]>--- scripts/qapi/parser.py | 44 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+)
Test coverage, please.
Re: [PATCH 4/8] qapi: detect potentially semantically ambiguous intro paragraphs
Quoted 8 lines · Markus Armbruster
Quoted 6 lines · John Snow
Cajole the QAPI Doc parser into yelping if a QAPI Doc Block contains more than one paragraph of plaintext and has no instances of Members, Errors, Returns, or Features that would naturally delineate an introduction from additional details such as notes, examples, and additional details.
Quoted 7 lines
Quoted 4 lines
Signed-off-by John Snow <[email protected]>--- scripts/qapi/parser.py | 44 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+)Test coverage, please.
Adding a FIXME for now. This patch is kind of a hack and we may find we want to refine it before merging, or maybe not.
Quoted 1 line
PATCH 5/8 qapi: re-order QAPI doc block sections
In reply to John SnowA forthcoming patch will enforce a rigid source order of QAPI Doc block sections:
(1) Intro
(2) Members
(3) Returns
(4) Errors
(5) Features
(6) Details
(7) Since
This patch specifically ensures the source ordering of items #1-6, with the positioning of "Since:" left for the following patch as it is a much bigger patch.
--- qapi/accelerator.json | 4 +-- qapi/block-core.json | 44 +++++++++++++------------- qapi/block-export.json | 20 ++++++------ qapi/block.json | 8 ++--- qapi/machine-s390x.json | 8 ++--- qapi/machine.json | 56 ++++++++++++++++----------------- qapi/misc.json | 4 +-- qapi/qom.json | 6 ++-- qapi/virtio.json | 32 +++++++++---------- tests/qapi-schema/doc-good.json | 8 ++--- tests/qapi-schema/doc-good.txt | 10 +++--- 11 files changed, 100 insertions(+), 100 deletions(-)
qapi/accelerator.json +2 -2
@@ -43,12 +43,12 @@ # # Query accelerator statistics # +# Returns: accelerator statistics +# # Features: # # @unstable: This command is meant for debugging. # -# Returns: accelerator statistics -# # Since: 10.1 ## { 'command': 'x-accel-stats',
qapi/block-core.json +22 -22
109 lines not on this page · raw message
qapi/block-export.json +10 -10
@@ -249,15 +249,15 @@ # The export name will be used as the id for the resulting block # export. # -# Features: -# -# @deprecated: This command is deprecated. Use `block-export-add` -# instead. -# # Errors: # - if the server is not running # - if an export with the same name already exists # +# Features: +# +# @deprecated: This command is deprecated. Use `block-export-add` +# instead. +# # Since: 1.3 ## { 'command': 'nbd-server-add',
@@ -297,16 +297,16 @@ # @mode: Mode of command operation. See `BlockExportRemoveMode` # description. Default is 'safe'. # -# Features: -# -# @deprecated: This command is deprecated. Use `block-export-del` -# instead. -# # Errors: # - if the server is not running # - if export is not found # - if mode is 'safe' and there are existing connections # +# Features: +# +# @deprecated: This command is deprecated. Use `block-export-del` +# instead. +# # Since: 2.12 ## { 'command': 'nbd-server-remove',
qapi/block.json +4 -4
@@ -109,13 +109,13 @@ # @force: If true, eject regardless of whether the drive is locked. # If not specified, the default value is false. # -# Features: -# -# @deprecated: Member @device is deprecated. Use @id instead. -# # Errors: # - If @device is not a valid block device, DeviceNotFound # +# Features: +# +# @deprecated: Member @device is deprecated. Use @id instead. +# # .. note:: Ejecting a device with no media results in success. # # Since: 0.14
qapi/machine-s390x.json +4 -4
@@ -108,12 +108,12 @@ ## # @query-s390x-cpu-polarization: # -# Features: -# -# @unstable: This command is experimental. -# # Returns: the machine's CPU polarization # +# Features: +# +# @unstable: This command is experimental. +# # Since: 8.2 ## { 'command': 'query-s390x-cpu-polarization', 'returns': 'CpuPolarizationInfo',
qapi/machine.json +28 -28
112 lines not on this page · raw message
qapi/misc.json +2 -2
@@ -209,14 +209,14 @@ # # @cpu-index: The CPU to use for commands that require an implicit CPU # +# Returns: the output of the command as a string +# # Features: # # @savevm-monitor-nodes: If present, HMP command savevm only snapshots # monitor-owned nodes if they have no parents. This allows the # use of 'savevm' with -blockdev. (since 4.2) # -# Returns: the output of the command as a string -# # Since: 0.14 # # .. note:: This command only exists as a stop-gap. Its use is highly
qapi/qom.json +3 -3
@@ -161,12 +161,12 @@ # @paths: The absolute or partial path for each object, as described # in `qom-get`. # -# Errors: -# - If any path is not valid or is ambiguous -# # Returns: A list where each element is the result for the # corresponding element of @paths. # +# Errors: +# - If any path is not valid or is ambiguous +# # Since 10.1 ## { 'command': 'qom-list-get',
qapi/virtio.json +16 -16
@@ -28,12 +28,12 @@ # # Return a list of all realized VirtIODevices # -# Features: -# -# @unstable: This command is meant for debugging. -# # Returns: List of gathered VirtIODevices # +# Features: +# +# @unstable: This command is meant for debugging. +# # Since: 7.2 # # .. qmp-example::
@@ -197,12 +197,12 @@ # # @path: Canonical QOM path of the VirtIODevice # -# Features: -# -# @unstable: This command is meant for debugging. -# # Returns: Status of the virtio device # +# Features: +# +# @unstable: This command is meant for debugging. +# # Since: 7.2 # # .. qmp-example::
@@ -566,12 +566,12 @@ # # @queue: VirtQueue index to examine # -# Features: -# -# @unstable: This command is meant for debugging. -# # Returns: Status of the queue # +# Features: +# +# @unstable: This command is meant for debugging. +# # .. note:: last_avail_idx will not be displayed in the case where the # selected VirtIODevice has a running vhost device and the # VirtIODevice VirtQueue index (queue) does not exist for the
@@ -701,12 +701,12 @@ # # @queue: vhost_virtqueue index to examine # -# Features: -# -# @unstable: This command is meant for debugging. -# # Returns: Status of the vhost_virtqueue # +# Features: +# +# @unstable: This command is meant for debugging. +# # Since: 7.2 # # .. qmp-example::
tests/qapi-schema/doc-good.json +4 -4
@@ -161,14 +161,14 @@ # @arg2: description starts on the same line # remainder indented differently # -# Features: -# @cmd-feat1: a feature -# @cmd-feat2: another feature -# # Returns: @Object # # Errors: some # +# Features: +# @cmd-feat1: a feature +# @cmd-feat2: another feature +# # .. note:: @arg3 is undocumented # # TODO: frobnicate
tests/qapi-schema/doc-good.txt +5 -5
@@ -115,17 +115,17 @@ Command cmd (Since: 2.10) * **arg3** ("boolean") -- Not documented - Features: - * **cmd-feat1** -- a feature - - * **cmd-feat2** -- another feature - Return: "Object" -- "Object" Errors: some + Features: + * **cmd-feat1** -- a feature + + * **cmd-feat2** -- another feature + Note: "arg3" is undocumented
Signature · 1 line
2.53.0
Re: [PATCH 5/8] qapi: re-order QAPI doc block sections
Quoted 11 lines · John Snow
A forthcoming patch will enforce a rigid source order of QAPI Doc block sections:
(1) Intro
(2) Members
(3) Returns
(4) Errors
(5) Features
(6) Details
(7) Since
Quoted 3 lines
This patch specifically ensures the source ordering of items #1-6, with the positioning of "Since:" left for the following patch as it is a much bigger patch.
It's actually the one after next. Suggest "left for a later patch".
Quoted 2 lines
Signed-off-by John Snow <[email protected]>
Re: [PATCH 5/8] qapi: re-order QAPI doc block sections
Quoted 13 lines · Markus Armbruster
Quoted 11 lines · John Snow
A forthcoming patch will enforce a rigid source order of QAPI Doc block sections:
(1) Intro
(2) Members
(3) Returns
(4) Errors
(5) Features
(6) Details
(7) Since
Quoted 6 lines
Quoted 3 lines
This patch specifically ensures the source ordering of items #1-6, with the positioning of "Since:" left for the following patch as it is a much bigger patch.
It's actually the one after next. Suggest "left for a later patch".
:)
Quoted 4 lines
Quoted 2 lines
Signed-off-by John Snow <[email protected]>
PATCH 6/8 qapi: enforce doc block section ordering
In reply to John SnowUgly hack, gets the job done. Likely many simplifications can be made as a result, but I didn't make any of them. There are some inconsistencies with human-readable vs ENUM_NAMES in error messages in this patch, but it appears to work anyway.
Consider this patch more of a rough idea and not anything approximating the kind of code you'd want to see from an Enterprise Linux Senior Software Engineer.
--- scripts/qapi/parser.py | 39 +++++++++++++++++++++++---------------- 1 file changed, 23 insertions(+), 16 deletions(-)
scripts/qapi/parser.py +23 -16
@@ -545,19 +545,25 @@ def get_doc(self) -> 'QAPIDoc': self.accept(False) line = self.get_doc_line() have_tagged = False - no_more_tags = False + last_section = QAPIDoc.Kind.INTRO def _tag_check(what: str) -> None: + nonlocal last_section + if what in ('TODO', 'Since'): return - if no_more_tags: + this_section = QAPIDoc.Kind.from_string(what) + if this_section.value < last_section.value: 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)." + f"'{what}' section cannot appear after " + f"'{last_section!s}' section, please re-order the " + "sections and adjust phrasing as necessary to ensure " + "consistent documentation flow between the source " + "code and the rendered HTML manual" ) + last_section = this_section while line is not None: # Blank lines
@@ -571,7 +577,7 @@ def _tag_check(what: str) -> None: if doc.features: raise QAPIParseError( self, "duplicated 'Features:' line") - _tag_check("Features") + _tag_check("FEATURE") self.accept(False) line = self.get_doc_line() while line == '':
@@ -589,7 +595,7 @@ def _tag_check(what: str) -> None: self, 'feature descriptions expected') have_tagged = True elif line == 'Details:': - _tag_check("Details") + _tag_check("DETAILS") self.accept(False) line = self.get_doc_line() while line == '':
@@ -598,6 +604,7 @@ def _tag_check(what: str) -> None: have_tagged = True elif match := self._match_at_name_colon(line): # description + _tag_check("MEMBER") if have_tagged: raise QAPIParseError( self,
@@ -654,13 +661,10 @@ def _tag_check(what: str) -> None: line = self.get_doc_indented(doc) 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. intro = not have_tagged + _tag_check("INTRO" if intro else "DETAILS") doc.ensure_untagged_section(self.info, intro) doc.append_line(line) line = self.get_doc_paragraph(doc)
@@ -703,14 +707,17 @@ class QAPIDoc: """ class Kind(enum.Enum): + # The order here is the order in which sections must appear in + # source code; with the exception of 'TODO' which may appear + # anywhere but is treated as a comment. INTRO = 0 MEMBER = 1 - FEATURE = 2 - RETURNS = 3 - ERRORS = 4 - SINCE = 5 + RETURNS = 2 + ERRORS = 3 + FEATURE = 4 + DETAILS = 5 TODO = 6 - DETAILS = 7 + SINCE = 7 @staticmethod def from_string(kind: str) -> 'QAPIDoc.Kind':
Signature · 1 line
2.53.0
Re: [PATCH 6/8] qapi: enforce doc block section ordering
Quoted 5 lines · John Snow
Ugly hack, gets the job done. Likely many simplifications can be made as a result, but I didn't make any of them. There are some inconsistencies with human-readable vs
ENUM_NAMESin error messages in this patch, but it appears to work anyway.
Quoted 8 lines
Consider this patch more of a rough idea and not anything approximating the kind of code you'd want to see from an Enterprise Linux Senior Software Engineer.
Signed-off-by John Snow <[email protected]>--- scripts/qapi/parser.py | 39 +++++++++++++++++++++++---------------- 1 file changed, 23 insertions(+), 16 deletions(-)
Missing: update to docs/devel/qapi-code-gen.rst. Suggest to put in a FIXME, so we don't forget.
Missing: test coverage.
Re: [PATCH 6/8] qapi: enforce doc block section ordering
Quoted 11 lines · Markus Armbruster
Quoted 9 lines · John Snow
Ugly hack, gets the job done. Likely many simplifications can be made as a result, but I didn't make any of them. There are some inconsistencies with human-readable vs
ENUM_NAMESin error messages in this patch, but it appears to work anyway.Consider this patch more of a rough idea and not anything approximating the kind of code you'd want to see from an Enterprise Linux Senior Software Engineer.
Quoted 8 lines
Quoted 4 lines
Signed-off-by John Snow <[email protected]>--- scripts/qapi/parser.py | 39 +++++++++++++++++++++++---------------- 1 file changed, 23 insertions(+), 16 deletions(-)Missing: update to
docs/devel/qapi-code-gen.rst. Suggest to put in a FIXME, so we don't forget.
ACK
Quoted 2 lines
Missing: test coverage.
Do we need to test every possible sequence, or just some characteristic examples...?
Quoted 1 line
Re: [PATCH 6/8] qapi: enforce doc block section ordering
Quoted 22 lines · John Snow
Quoted 11 lines · Markus Armbruster
Quoted 9 lines · John Snow
Ugly hack, gets the job done. Likely many simplifications can be made as a result, but I didn't make any of them. There are some inconsistencies with human-readable vs
ENUM_NAMESin error messages in this patch, but it appears to work anyway.Consider this patch more of a rough idea and not anything approximating the kind of code you'd want to see from an Enterprise Linux Senior Software Engineer.
Quoted 8 lines
Quoted 4 lines
Signed-off-by John Snow <[email protected]>--- scripts/qapi/parser.py | 39 +++++++++++++++++++++++---------------- 1 file changed, 23 insertions(+), 16 deletions(-)Missing: update to
docs/devel/qapi-code-gen.rst. Suggest to put in a FIXME, so we don't forget.
Quoted 8 lines
ACK
Quoted 2 lines
Missing: test coverage.
Do we need to test every possible sequence, or just some characteristic examples...?
Let's start with characteristic examples.
PATCH 7/8 qapi: re-order 'since' sections to always be last
In reply to John SnowNote that with "Since" being moved to the last position, we open up a good many new cases of ambiguos intro-vs-details text which must be corrected with "Details:" tags.
This patch doesn't only add these markers where it would definitively impact inlining - it adds them to *any* doc block that has more than one paragraph of plaintext and no other distinguishing features (members, features, errors, returns).
It may well be the case that not every last one of these *needs* to be amended in this way, but this is the broad coverage shotgun approach that demonstrates which places in the code may cause footguns with regards to automated stub insertions of members/arguments/etc, returns, or inlining order ambiguities.
--- docs/interop/firmware.json | 4 +- docs/interop/vhost-user.json | 3 +- qapi/accelerator.json | 8 +-- qapi/acpi.json | 8 ++- qapi/block-core.json | 136 ++++++++++++++++++----------------- qapi/block.json | 40 +++++------ qapi/char.json | 36 +++++----- qapi/control.json | 14 ++-- qapi/dump.json | 16 ++--- qapi/machine-s390x.json | 8 +-- qapi/machine.json | 86 ++++++++++++---------- qapi/migration.json | 94 ++++++++++++------------ qapi/misc-arm.json | 6 +- qapi/misc-i386.json | 40 ++++++----- qapi/misc.json | 64 +++++++++-------- qapi/net.json | 40 +++++------ qapi/pci.json | 4 +- qapi/qdev.json | 12 ++-- qapi/qom.json | 20 +++--- qapi/replay.json | 16 +++-- qapi/rocker.json | 16 ++--- qapi/run-state.json | 66 ++++++++++------- qapi/tpm.json | 12 ++-- qapi/trace.json | 8 +-- qapi/transaction.json | 4 +- qapi/ui.json | 76 +++++++++++--------- qapi/vfio.json | 4 +- qapi/virtio.json | 20 +++--- 28 files changed, 463 insertions(+), 398 deletions(-)
docs/interop/firmware.json +2 -2
@@ -551,8 +551,6 @@ # debugging purposes only, and management software shall # explicitly ignore it. # -# Since: 3.0 -# # .. qmp-example:: # # {
@@ -752,6 +750,8 @@ # "-D DEBUG_PRINT_ERROR_LEVEL=0x80000000" # ] # } +# +# Since: 3.0 ## { 'struct' : 'Firmware', 'data' : { 'description' : 'str',
docs/interop/vhost-user.json +1 -2
@@ -264,8 +264,6 @@ # development and debugging purposes only, and management software # shall explicitly ignore it. # -# Since: 4.0 -# # .. qmp-example: # # {
@@ -278,6 +276,7 @@ # ] # } # +# Since: 4.0 ## { 'struct' : 'VhostUserBackend',
qapi/accelerator.json +4 -4
@@ -29,12 +29,12 @@ # # Return information about KVM acceleration # -# Since: 0.14 -# # .. qmp-example:: # # -> { "execute": "query-kvm" } # <- { "return": { "enabled": true, "present": true } } +# +# Since: 0.14 ## { 'command': 'query-kvm', 'returns': 'KvmInfo' }
@@ -101,11 +101,11 @@ # # Returns: @AcceleratorInfo # -# Since: 10.2.0 -# # .. qmp-example:: # # -> { "execute": "query-accelerators" } # <- { "return": { "enabled": "mshv", "present": ["kvm", "mshv", "qtest", "tcg"] } } +# +# Since: 10.2.0 ## { 'command': 'query-accelerators', 'returns': 'AcceleratorInfo' }
qapi/acpi.json +5 -3
@@ -111,7 +111,7 @@ # Return a list of `ACPIOSTInfo` for devices that support status # reporting via ACPI _OST method. # -# Since: 2.1 +# Details: # # .. qmp-example:: #
@@ -121,6 +121,8 @@ # { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0}, # { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0} # ]} +# +# Since: 2.1 ## { 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] }
@@ -131,14 +133,14 @@ # # @info: OSPM Status Indication # -# Since: 2.1 -# # .. qmp-example:: # # <- { "event": "ACPI_DEVICE_OST", # "data": { "info": { "device": "d1", "slot": "0", # "slot-type": "DIMM", "source": 1, "status": 0 } }, # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } +# +# Since: 2.1 ## { 'event': 'ACPI_DEVICE_OST', 'data': { 'info': 'ACPIOSTInfo' } }
qapi/block-core.json +69 -67
536 lines not on this page · raw message
qapi/block.json +20 -20
@@ -118,12 +118,12 @@ # # .. note:: Ejecting a device with no media results in success. # -# Since: 0.14 -# # .. qmp-example:: # # -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } } # <- { "return": {} } +# +# Since: 0.14 ## { 'command': 'eject', 'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] },
@@ -162,8 +162,6 @@ # # @deprecated: Member @device is deprecated. Use @id instead. # -# Since: 2.5 -# # .. qmp-example:: # # -> { "execute": "blockdev-open-tray",
@@ -177,6 +175,8 @@ # "tray-open": true } } # # <- { "return": {} } +# +# Since: 2.5 ## { 'command': 'blockdev-open-tray', 'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] },
@@ -200,8 +200,6 @@ # # @deprecated: Member @device is deprecated. Use @id instead. # -# Since: 2.5 -# # .. qmp-example:: # # -> { "execute": "blockdev-close-tray",
@@ -215,6 +213,8 @@ # "tray-open": false } } # # <- { "return": {} } +# +# Since: 2.5 ## { 'command': 'blockdev-close-tray', 'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] },
@@ -232,8 +232,6 @@ # # @id: The name or QOM path of the guest device # -# Since: 2.12 -# # .. qmp-example:: # # -> { "execute": "blockdev-remove-medium",
@@ -258,6 +256,8 @@ # "arguments": { "id": "ide0-1-0" } } # # <- { "return": {} } +# +# Since: 2.12 ## { 'command': 'blockdev-remove-medium', 'data': { 'id': 'str' } }
@@ -273,8 +273,6 @@ # # @node-name: name of a node in the block driver state graph # -# Since: 2.12 -# # .. qmp-example:: # # -> { "execute": "blockdev-add",
@@ -290,6 +288,8 @@ # "node-name": "node0" } } # # <- { "return": {} } +# +# Since: 2.12 ## { 'command': 'blockdev-insert-medium', 'data': { 'id': 'str',
@@ -343,8 +343,6 @@ # # @deprecated: Member @device is deprecated. Use @id instead. # -# Since: 2.5 -# # .. qmp-example:: # :title: Change a removable medium #
@@ -374,6 +372,8 @@ # "read-only-mode": "read-only" } } # # <- { "return": {} } +# +# Since: 2.5 ## { 'command': 'blockdev-change-medium', 'data': { '*device': { 'type': 'str', 'features': [ 'deprecated' ] },
@@ -398,8 +398,6 @@ # @tray-open: true if the tray has been opened or false if it has been # closed # -# Since: 1.1 -# # .. qmp-example:: # # <- { "event": "DEVICE_TRAY_MOVED",
@@ -408,6 +406,8 @@ # "tray-open": true # }, # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } +# +# Since: 1.1 ## { 'event': 'DEVICE_TRAY_MOVED', 'data': { 'device': 'str', 'id': 'str', 'tray-open': 'bool' } }
@@ -422,8 +422,6 @@ # # @connected: true if the PR manager is connected to a backend # -# Since: 3.0 -# # .. qmp-example:: # # <- { "event": "PR_MANAGER_STATUS_CHANGED",
@@ -431,6 +429,8 @@ # "connected": true # }, # "timestamp": { "seconds": 1519840375, "microseconds": 450486 } } +# +# Since: 3.0 ## { 'event': 'PR_MANAGER_STATUS_CHANGED', 'data': { 'id': 'str', 'connected': 'bool' } }
@@ -464,8 +464,6 @@ # Errors: # - If @device is not a valid block device, DeviceNotFound # -# Since: 1.1 -# # .. qmp-example:: # # -> { "execute": "block_set_io_throttle",
@@ -505,6 +503,8 @@ # "bps_max_length": 60, # "iops_size": 0 } } # <- { "return": {} } +# +# Since: 1.1 ## { 'command': 'block_set_io_throttle', 'boxed': true, 'data': 'BlockIOThrottle',
@@ -546,8 +546,6 @@ # Errors: # - if device is not found or any boundary arrays are invalid. # -# Since: 4.0 -# # .. qmp-example:: # :annotated: #
@@ -594,6 +592,8 @@ # -> { "execute": "block-latency-histogram-set", # "arguments": { "id": "drive0" } } # <- { "return": {} } +# +# Since: 4.0 ## { 'command': 'block-latency-histogram-set', 'data': {'id': 'str',
qapi/char.json +18 -18
@@ -38,8 +38,6 @@ # # Return information about current character devices. # -# Since: 0.14 -# # .. qmp-example:: # # -> { "execute": "query-chardev" }
@@ -62,6 +60,8 @@ # } # ] # } +# +# Since: 0.14 ## { 'command': 'query-chardev', 'returns': ['ChardevInfo'], 'allow-preconfig': true }
@@ -82,8 +82,6 @@ # # Return information about character device backends. # -# Since: 2.0 -# # .. qmp-example:: # # -> { "execute": "query-chardev-backends" }
@@ -103,6 +101,8 @@ # } # ] # } +# +# Since: 2.0 ## { 'command': 'query-chardev-backends', 'returns': ['ChardevBackendInfo'] }
@@ -137,8 +137,6 @@ # - data itself is always Unicode regardless of format, like any # other string. # -# Since: 1.4 -# # .. qmp-example:: # # -> { "execute": "ringbuf-write",
@@ -146,6 +144,8 @@ # "data": "abcdefgh", # "format": "utf8" } } # <- { "return": {} } +# +# Since: 1.4 ## { 'command': 'ringbuf-write', 'data': { 'device': 'str',
@@ -173,8 +173,6 @@ # # Returns: data read from the device # -# Since: 1.4 -# # .. qmp-example:: # # -> { "execute": "ringbuf-read",
@@ -182,6 +180,8 @@ # "size": 1000, # "format": "utf8" } } # <- { "return": "abcdefgh" } +# +# Since: 1.4 ## { 'command': 'ringbuf-read', 'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'},
@@ -761,8 +761,6 @@ # # @backend: backend type and parameters # -# Since: 1.4 -# # .. qmp-example:: # # -> { "execute" : "chardev-add",
@@ -784,6 +782,8 @@ # "arguments" : { "id" : "baz", # "backend" : { "type" : "pty", "data" : {} } } } # <- { "return": { "pty" : "/dev/pty/42" } } +# +# Since: 1.4 ## { 'command': 'chardev-add', 'data': { 'id': 'str',
@@ -799,8 +799,6 @@ # # @backend: new backend type and parameters # -# Since: 2.10 -# # .. qmp-example:: # # -> { "execute" : "chardev-change",
@@ -825,6 +823,8 @@ # "server" : true, # "wait" : false }}}} # <- {"return": {}} +# +# Since: 2.10 ## { 'command': 'chardev-change', 'data': { 'id': 'str',
@@ -838,12 +838,12 @@ # # @id: the chardev's ID, must exist and not be in use # -# Since: 1.4 -# # .. qmp-example:: # # -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } } # <- { "return": {} } +# +# Since: 1.4 ## { 'command': 'chardev-remove', 'data': { 'id': 'str' } }
@@ -855,12 +855,12 @@ # # @id: the chardev's ID, must exist # -# Since: 2.10 -# # .. qmp-example:: # # -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } } # <- { "return": {} } +# +# Since: 2.10 ## { 'command': 'chardev-send-break', 'data': { 'id': 'str' } }
@@ -876,13 +876,13 @@ # # .. note:: This event is rate-limited. # -# Since: 2.1 -# # .. qmp-example:: # # <- { "event": "VSERPORT_CHANGE", # "data": { "id": "channel0", "open": true }, # "timestamp": { "seconds": 1401385907, "microseconds": 422329 } } +# +# Since: 2.1 ## { 'event': 'VSERPORT_CHANGE', 'data': { 'id': 'str',
qapi/control.json +8 -6
@@ -97,8 +97,6 @@ # # Returns: An object describing the current version of QEMU. # -# Since: 0.14 -# # .. qmp-example:: # # -> { "execute": "query-version" }
@@ -112,6 +110,8 @@ # "package":"" # } # } +# +# Since: 0.14 ## { 'command': 'query-version', 'returns': 'VersionInfo', 'allow-preconfig': true }
@@ -134,8 +134,6 @@ # # Returns: A list of all supported commands # -# Since: 0.14 -# # .. qmp-example:: # # -> { "execute": "query-commands" }
@@ -152,6 +150,8 @@ # } # # This example has been shortened as the real response is too long. +# +# Since: 0.14 ## { 'command': 'query-commands', 'returns': ['CommandInfo'], 'allow-preconfig': true }
@@ -161,16 +161,18 @@ # # Request graceful QEMU process termination. # +# Details: +# # While every attempt is made to send the QMP response before # terminating, this is not guaranteed. When using this interface, a # premature EOF would not be unexpected. # -# Since: 0.14 -# # .. qmp-example:: # # -> { "execute": "quit" } # <- { "return": {} } +# +# Since: 0.14 ## { 'command': 'quit', 'allow-preconfig': true }
qapi/dump.json +8 -8
@@ -94,13 +94,13 @@ # # .. note:: All boolean arguments default to false. # -# Since: 1.2 -# # .. qmp-example:: # # -> { "execute": "dump-guest-memory", # "arguments": { "paging": false, "protocol": "fd:dump" } } # <- { "return": {} } +# +# Since: 1.2 ## { 'command': 'dump-guest-memory', 'data': { 'paging': 'bool', 'protocol': 'str', '*detach': 'bool',
@@ -150,13 +150,13 @@ # # Returns: An object showing the dump status. # -# Since: 2.6 -# # .. qmp-example:: # # -> { "execute": "query-dump" } # <- { "return": { "status": "active", "completed": 1024000, # "total": 2048000 } } +# +# Since: 2.6 ## { 'command': 'query-dump', 'returns': 'DumpQueryResult' }
@@ -171,14 +171,14 @@ # failed. Only presents on failure. The user should not try to # interpret the error string. # -# Since: 2.6 -# # .. qmp-example:: # # <- { "event": "DUMP_COMPLETED", # "data": { "result": { "total": 1090650112, "status": "completed", # "completed": 1090650112 } }, # "timestamp": { "seconds": 1648244171, "microseconds": 950316 } } +# +# Since: 2.6 ## { 'event': 'DUMP_COMPLETED' , 'data': { 'result': 'DumpQueryResult', '*error': 'str' } }
@@ -201,13 +201,13 @@ # # Returns: An object listing available formats for `dump-guest-memory` # -# Since: 2.0 -# # .. qmp-example:: # # -> { "execute": "query-dump-guest-memory-capability" } # <- { "return": { "formats": # ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } } +# +# Since: 2.0 ## { 'command': 'query-dump-guest-memory-capability', 'returns': 'DumpGuestMemoryCapability' }
qapi/machine-s390x.json +4 -4
@@ -79,13 +79,13 @@ # # @unstable: This event is experimental. # -# Since: 8.2 -# # .. qmp-example:: # # <- { "event": "CPU_POLARIZATION_CHANGE", # "data": { "polarization": "horizontal" }, # "timestamp": { "seconds": 1401385907, "microseconds": 422329 } } +# +# Since: 8.2 ## { 'event': 'CPU_POLARIZATION_CHANGE', 'data': { 'polarization': 'S390CpuPolarization' },
@@ -130,12 +130,12 @@ # # @unstable: This event is experimental. # -# Since: 10.2 -# # .. qmp-example:: # # <- { "event": "SCLP_CPI_INFO_AVAILABLE", # "timestamp": { "seconds": 1401385907, "microseconds": 422329 } } +# +# Since: 10.2 ## { 'event': 'SCLP_CPI_INFO_AVAILABLE', 'features': [ 'unstable' ]
qapi/machine.json +50 -36
329 lines not on this page · raw message
qapi/migration.json +50 -44
356 lines not on this page · raw message
qapi/misc-arm.json +4 -2
@@ -33,15 +33,17 @@ # It will return a list of `GICCapability` objects that describe its # capability bits. # +# Details: +# # On non-ARM targets this command will report an error as the GIC # technology is not applicable. # -# Since: 2.6 -# # .. qmp-example:: # # -> { "execute": "query-gic-capabilities" } # <- { "return": [{ "version": 2, "emulated": true, "kernel": false }, # { "version": 3, "emulated": false, "kernel": true } ] } +# +# Since: 2.6 ## { 'command': 'query-gic-capabilities', 'returns': ['GICCapability'] }
qapi/misc-i386.json +24 -16
@@ -10,16 +10,18 @@ # mechanism to synchronize guest time is in effect, for example QEMU # guest agent's `guest-set-time` command. # +# Details: +# # Use of this command is only applicable for x86 machines with an RTC, # and on other machines will silently return without performing any # action. # -# Since: 2.1 -# # .. qmp-example:: # # -> { "execute": "rtc-reset-reinjection" } # <- { "return": {} } +# +# Since: 2.1 ## { 'command': 'rtc-reset-reinjection' }
@@ -127,18 +129,20 @@ # # Return information about SEV/SEV-ES/SEV-SNP. # +# Details: +# # If unavailable due to an incompatible configuration the returned # @enabled field is set to 'false' and the state of all other fields # is unspecified. # -# Since: 2.12 -# # .. qmp-example:: # # -> { "execute": "query-sev" } # <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0, # "build-id" : 0, "policy" : 0, "state" : "running", # "handle" : 1 } } +# +# Since: 2.12 ## { 'command': 'query-sev', 'returns': 'SevInfo' }
@@ -169,12 +173,12 @@ # invalid guest configuration or if the guest has not reached # the required SEV state, GenericError # -# Since: 2.12 -# # .. qmp-example:: # # -> { "execute": "query-sev-launch-measure" } # <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } } +# +# Since: 2.12 ## { 'command': 'query-sev-launch-measure', 'returns': 'SevLaunchMeasureInfo' }
@@ -214,14 +218,14 @@ # Errors: # - If SEV is not available on the platform, GenericError # -# Since: 2.12 -# # .. qmp-example:: # # -> { "execute": "query-sev-capabilities" } # <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE", # "cpu0-id": "2lvmGwo+...61iEinw==", # "cbitpos": 47, "reduced-phys-bits": 1}} +# +# Since: 2.12 ## { 'command': 'query-sev-capabilities', 'returns': 'SevCapability' }
@@ -280,13 +284,13 @@ # invalid guest configuration or because the guest has not # reached the required SEV state, GenericError # -# Since: 6.1 -# # .. qmp-example:: # # -> { "execute" : "query-sev-attestation-report", # "arguments": { "mnonce": "aaaaaaa" } } # <- { "return" : { "data": "aaaaaaaabbbddddd"} } +# +# Since: 6.1 ## { 'command': 'query-sev-attestation-report', 'data': { 'mnonce': 'str' },
@@ -336,7 +340,7 @@ # # Return information about configured SGX capabilities of guest # -# Since: 6.2 +# Details: # # .. qmp-example:: #
@@ -345,6 +349,8 @@ # "flc": true, # "sections": [{"node": 0, "size": 67108864}, # {"node": 1, "size": 29360128}]} } +# +# Since: 6.2 ## { 'command': 'query-sgx', 'returns': 'SgxInfo' }
@@ -353,7 +359,7 @@ # # Return information about SGX capabilities of host # -# Since: 6.2 +# Details: # # .. qmp-example:: #
@@ -362,6 +368,8 @@ # "flc": true, # "section" : [{"node": 0, "size": 67108864}, # {"node": 1, "size": 29360128}]} } +# +# Since: 6.2 ## { 'command': 'query-sgx-capabilities', 'returns': 'SgxInfo' }
@@ -424,8 +432,6 @@ # # Returns: list of open event channel ports. # -# Since: 8.0 -# # .. qmp-example:: # # -> { "execute": "xen-event-list" }
@@ -450,6 +456,8 @@ # } # ] # } +# +# Since: 8.0 ## { 'command': 'xen-event-list', 'returns': ['EvtchnInfo'] }
@@ -461,12 +469,12 @@ # # @port: The port number # -# Since: 8.0 -# # .. qmp-example:: # # -> { "execute": "xen-event-inject", "arguments": { "port": 1 } } # <- { "return": { } } +# +# Since: 8.0 ## { 'command': 'xen-event-inject', 'data': { 'port': 'uint32' } }
qapi/misc.json +35 -29
246 lines not on this page · raw message
qapi/net.json +20 -20
@@ -22,8 +22,6 @@ # Errors: # - If @name is not a valid network device, DeviceNotFound # -# Since: 0.14 -# # .. note:: Not all network adapters support setting link status. # This command will succeed even if the network adapter does not # support link status notification.
@@ -33,6 +31,8 @@ # -> { "execute": "set_link", # "arguments": { "name": "e1000.0", "up": false } } # <- { "return": {} } +# +# Since: 0.14 ## { 'command': 'set_link', 'data': {'name': 'str', 'up': 'bool'} }
@@ -43,8 +43,6 @@ # # Additional arguments depend on the type. # -# Since: 0.14 -# # Errors: # - If @type is not a valid network backend, DeviceNotFound #
@@ -54,6 +52,8 @@ # "arguments": { "type": "user", "id": "netdev1", # "dnssearch": [ { "str": "example.org" } ] } } # <- { "return": {} } +# +# Since: 0.14 ## { 'command': 'netdev_add', 'data': 'Netdev', 'boxed': true, 'allow-preconfig': true }
@@ -68,12 +68,12 @@ # Errors: # - If @id is not a valid network backend, DeviceNotFound # -# Since: 0.14 -# # .. qmp-example:: # # -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } } # <- { "return": {} } +# +# Since: 0.14 ## { 'command': 'netdev_del', 'data': {'id': 'str'}, 'allow-preconfig': true }
@@ -975,8 +975,6 @@ # - if the given NIC doesn't support rx-filter querying # - if the given net client isn't a NIC # -# Since: 1.6 -# # .. qmp-example:: # # -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
@@ -1005,6 +1003,8 @@ # } # ] # } +# +# Since: 1.6 ## { 'command': 'query-rx-filter', 'data': { '*name': 'str' },
@@ -1020,14 +1020,14 @@ # # @path: device path # -# Since: 1.6 -# # .. qmp-example:: # # <- { "event": "NIC_RX_FILTER_CHANGED", # "data": { "name": "vnet0", # "path": "/machine/peripheral/vnet0/virtio-backend" }, # "timestamp": { "seconds": 1368697518, "microseconds": 326866 } } +# +# Since: 1.6 ## { 'event': 'NIC_RX_FILTER_CHANGED', 'data': { '*name': 'str', 'path': 'str' } }
@@ -1095,13 +1095,13 @@ # # @device-id: QEMU device id of the unplugged device # -# Since: 4.2 -# # .. qmp-example:: # # <- { "event": "FAILOVER_NEGOTIATED", # "data": { "device-id": "net1" }, # "timestamp": { "seconds": 1368697518, "microseconds": 326866 } } +# +# Since: 4.2 ## { 'event': 'FAILOVER_NEGOTIATED', 'data': {'device-id': 'str'} }
@@ -1115,8 +1115,6 @@ # # @addr: The destination address # -# Since: 7.2 -# # .. qmp-example:: # # <- { "event": "NETDEV_STREAM_CONNECTED",
@@ -1131,6 +1129,8 @@ # "data": { "netdev-id": "netdev0", # "addr": { "path": "/tmp/qemu0", "type": "unix" } }, # "timestamp": { "seconds": 1666269706, "microseconds": 413651 } } +# +# Since: 7.2 ## { 'event': 'NETDEV_STREAM_CONNECTED', 'data': { 'netdev-id': 'str',
@@ -1143,13 +1143,13 @@ # # @netdev-id: QEMU netdev id that is disconnected # -# Since: 7.2 -# # .. qmp-example:: # # <- { "event": "NETDEV_STREAM_DISCONNECTED", # "data": {"netdev-id": "netdev0"}, # "timestamp": {"seconds": 1663330937, "microseconds": 526695} } +# +# Since: 7.2 ## { 'event': 'NETDEV_STREAM_DISCONNECTED', 'data': { 'netdev-id': 'str' } }
@@ -1163,13 +1163,13 @@ # # @chardev-id: The character device id used by the QEMU netdev # -# Since: 10.0 -# # .. qmp-example:: # # <- { "timestamp": {"seconds": 1739538638, "microseconds": 354181 }, # "event": "NETDEV_VHOST_USER_CONNECTED", # "data": { "netdev-id": "netdev0", "chardev-id": "chr0" } } +# +# Since: 10.0 ## { 'event': 'NETDEV_VHOST_USER_CONNECTED', 'data': { 'netdev-id': 'str', 'chardev-id': 'str' } }
@@ -1181,13 +1181,13 @@ # # @netdev-id: QEMU netdev id that is disconnected # -# Since: 10.0 -# # .. qmp-example:: # # <- { "timestamp": { "seconds": 1739538634, "microseconds": 920450 }, # "event": "NETDEV_VHOST_USER_DISCONNECTED", # "data": { "netdev-id": "netdev0" } } +# +# Since: 10.0 ## { 'event': 'NETDEV_VHOST_USER_DISCONNECTED', 'data': { 'netdev-id': 'str' } }
qapi/pci.json +2 -2
@@ -182,8 +182,6 @@ # of all PCI devices attached to it. Each device is represented # by a json-object. # -# Since: 0.14 -# # .. qmp-example:: # # -> { "execute": "query-pci" }
@@ -314,5 +312,7 @@ # } # # This example has been shortened as the real response is too long. +# +# Since: 0.14 ## { 'command': 'query-pci', 'returns': ['PciInfo'] }
qapi/qdev.json +6 -6
@@ -103,8 +103,6 @@ # device will not be removed and a `DEVICE_UNPLUG_GUEST_ERROR` # event is sent. Some errors cannot be detected. # -# Since: 0.14 -# # .. qmp-example:: # # -> { "execute": "device_del",
@@ -116,6 +114,8 @@ # -> { "execute": "device_del", # "arguments": { "id": "/machine/peripheral-anon/device[0]" } } # <- { "return": {} } +# +# Since: 0.14 ## { 'command': 'device_del', 'data': {'id': 'str'} }
@@ -131,14 +131,14 @@ # # @path: the device's QOM path # -# Since: 1.5 -# # .. qmp-example:: # # <- { "event": "DEVICE_DELETED", # "data": { "device": "virtio-net-pci-0", # "path": "/machine/peripheral/virtio-net-pci-0" }, # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } +# +# Since: 1.5 ## { 'event': 'DEVICE_DELETED', 'data': { '*device': 'str', 'path': 'str' } }
@@ -153,14 +153,14 @@ # # @path: the device's QOM path # -# Since: 6.2 -# # .. qmp-example:: # # <- { "event": "DEVICE_UNPLUG_GUEST_ERROR", # "data": { "device": "core1", # "path": "/machine/peripheral/core1" }, # "timestamp": { "seconds": 1615570772, "microseconds": 202844 } } +# +# Since: 6.2 ## { 'event': 'DEVICE_UNPLUG_GUEST_ERROR', 'data': { '*device': 'str', 'path': 'str' } }
qapi/qom.json +10 -10
@@ -85,8 +85,6 @@ # # Returns: a list that describe the properties of the object. # -# Since: 1.2 -# # .. qmp-example:: # # -> { "execute": "qom-list",
@@ -95,6 +93,8 @@ # { "name": "parallel0", "type": "child<chardev-vc>" }, # { "name": "serial0", "type": "child<chardev-vc>" }, # { "name": "mon0", "type": "child<chardev-stdio>" } ] } +# +# Since: 1.2 ## { 'command': 'qom-list', 'data': { 'path': 'str' },
@@ -129,8 +129,6 @@ # child<> and link<> properties are returned as #str pathnames. # All integer property types (u8, u16, etc) are returned as #int. # -# Since: 1.2 -# # .. qmp-example:: # :title: Use absolute path #
@@ -146,6 +144,8 @@ # "arguments": { "path": "unattached/sysbus", # "property": "type" } } # <- { "return": "System" } +# +# Since: 1.2 ## { 'command': 'qom-get', 'data': { 'path': 'str', 'property': 'str' },
@@ -186,8 +186,6 @@ # @value: a value who's type is appropriate for the property type. # See `qom-get` for a description of type mapping. # -# Since: 1.2 -# # .. qmp-example:: # # -> { "execute": "qom-set",
@@ -195,6 +193,8 @@ # "property": "graphics", # "value": false } } # <- { "return": {} } +# +# Since: 1.2 ## { 'command': 'qom-set', 'data': { 'path': 'str', 'property': 'str', 'value': 'any' },
@@ -1342,14 +1342,14 @@ # Errors: # - If @qom-type is not a valid class name # -# Since: 2.0 -# # .. qmp-example:: # # -> { "execute": "object-add", # "arguments": { "qom-type": "rng-random", "id": "rng1", # "filename": "/dev/hwrng" } } # <- { "return": {} } +# +# Since: 2.0 ## { 'command': 'object-add', 'data': 'ObjectOptions', 'boxed': true, 'allow-preconfig': true }
@@ -1364,12 +1364,12 @@ # Errors: # - If @id is not a valid id for a QOM object # -# Since: 2.0 -# # .. qmp-example:: # # -> { "execute": "object-del", "arguments": { "id": "rng1" } } # <- { "return": {} } +# +# Since: 2.0 ## { 'command': 'object-del', 'data': {'id': 'str'}, 'allow-preconfig': true }
qapi/replay.json +9 -7
@@ -54,12 +54,12 @@ # # Returns: record/replay information. # -# Since: 5.2 -# # .. qmp-example:: # # -> { "execute": "query-replay" } # <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } } +# +# Since: 5.2 ## { 'command': 'query-replay', 'returns': 'ReplayInfo' }
@@ -76,12 +76,12 @@ # # @icount: instruction count to stop at # -# Since: 5.2 -# # .. qmp-example:: # # -> { "execute": "replay-break", "arguments": { "icount": 220414 } } # <- { "return": {} } +# +# Since: 5.2 ## { 'command': 'replay-break', 'data': { 'icount': 'int' } }
@@ -91,12 +91,14 @@ # Remove replay breakpoint which was set with `replay-break`. The # command is ignored when there are no replay breakpoints. # -# Since: 5.2 +# Details: # # .. qmp-example:: # # -> { "execute": "replay-delete-break" } # <- { "return": {} } +# +# Since: 5.2 ## { 'command': 'replay-delete-break' }
@@ -112,11 +114,11 @@ # # @icount: target instruction count # -# Since: 5.2 -# # .. qmp-example:: # # -> { "execute": "replay-seek", "arguments": { "icount": 220414 } } # <- { "return": {} } +# +# Since: 5.2 ## { 'command': 'replay-seek', 'data': { 'icount': 'int' } }
qapi/rocker.json +8 -8
@@ -30,12 +30,12 @@ # # @name: switch name # -# Since: 2.4 -# # .. qmp-example:: # # -> { "execute": "query-rocker", "arguments": { "name": "sw1" } } # <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}} +# +# Since: 2.4 ## { 'command': 'query-rocker', 'data': { 'name': 'str' },
@@ -98,8 +98,6 @@ # # @name: port name # -# Since: 2.4 -# # .. qmp-example:: # # -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
@@ -108,6 +106,8 @@ # {"duplex": "full", "enabled": true, "name": "sw1.2", # "autoneg": "off", "link-up": true, "speed": 10000} # ]} +# +# Since: 2.4 ## { 'command': 'query-rocker-ports', 'data': { 'name': 'str' },
@@ -240,8 +240,6 @@ # # Returns: rocker OF-DPA flow information # -# Since: 2.4 -# # .. qmp-example:: # # -> { "execute": "query-rocker-of-dpa-flows",
@@ -254,6 +252,8 @@ # }, # ... # ]} +# +# Since: 2.4 ## { 'command': 'query-rocker-of-dpa-flows', 'data': { 'name': 'str', '*tbl-id': 'uint32' },
@@ -315,8 +315,6 @@ # # Returns: rocker OF-DPA group information # -# Since: 2.4 -# # .. qmp-example:: # # -> { "execute": "query-rocker-of-dpa-groups",
@@ -334,6 +332,8 @@ # "pport": 0, "vlan-id": 3840, # "pop-vlan": 1, "id": 251658240} # ]} +# +# Since: 2.4 ## { 'command': 'query-rocker-of-dpa-groups', 'data': { 'name': 'str', '*type': 'uint8' },
qapi/run-state.json +41 -25
247 lines not on this page · raw message
qapi/tpm.json +6 -6
@@ -29,12 +29,12 @@ # # Return a list of supported TPM models # -# Since: 1.5 -# # .. qmp-example:: # # -> { "execute": "query-tpm-models" } # <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] } +# +# Since: 1.5 ## { 'command': 'query-tpm-models', 'returns': ['TpmModel'], 'if': 'CONFIG_TPM' }
@@ -58,12 +58,12 @@ # # Return a list of supported TPM types # -# Since: 1.5 -# # .. qmp-example:: # # -> { "execute": "query-tpm-types" } # <- { "return": [ "passthrough", "emulator" ] } +# +# Since: 1.5 ## { 'command': 'query-tpm-types', 'returns': ['TpmType'], 'if': 'CONFIG_TPM' }
@@ -164,8 +164,6 @@ # # Return information about the TPM device # -# Since: 1.5 -# # .. qmp-example:: # # -> { "execute": "query-tpm" }
@@ -183,6 +181,8 @@ # } # ] # } +# +# Since: 1.5 ## { 'command': 'query-tpm', 'returns': ['TPMInfo'], 'if': 'CONFIG_TPM' }
qapi/trace.json +4 -4
@@ -51,13 +51,13 @@ # # Returns: a list of info for the matching events # -# Since: 2.2 -# # .. qmp-example:: # # -> { "execute": "trace-event-get-state", # "arguments": { "name": "qemu_memalign" } } # <- { "return": [ { "name": "qemu_memalign", "state": "disabled", "vcpu": false } ] } +# +# Since: 2.2 ## { 'command': 'trace-event-get-state', 'data': {'name': 'str' },
@@ -74,13 +74,13 @@ # # @ignore-unavailable: Do not match unavailable events with @name. # -# Since: 2.2 -# # .. qmp-example:: # # -> { "execute": "trace-event-set-state", # "arguments": { "name": "qemu_memalign", "enable": true } } # <- { "return": {} } +# +# Since: 2.2 ## { 'command': 'trace-event-set-state', 'data': {'name': 'str', 'enable': 'bool', '*ignore-unavailable': 'bool' } }
qapi/transaction.json +2 -2
@@ -244,8 +244,6 @@ # in an error condition, and subsequent actions will not have been # attempted. # -# Since: 1.1 -# # .. qmp-example:: # # -> { "execute": "transaction",
@@ -266,6 +264,8 @@ # "device": "ide-hd2", # "name": "snapshot0" } } ] } } # <- { "return": {} } +# +# Since: 1.1 ## { 'command': 'transaction', 'data': { 'actions': [ 'TransactionAction' ],
qapi/ui.json +41 -35
86 lines not on this page · raw message
The rest of this diff is not shown. View the raw message.
Signature · 1 line
2.53.0
Part of the diff is not shown here. View the raw message.
Re: [PATCH 7/8] qapi: re-order 'since' sections to always be last
Quoted 16 lines · John Snow
Note that with "Since" being moved to the last position, we open up a good many new cases of ambiguos intro-vs-details text which must be corrected with "Details:" tags.
This patch doesn't only add these markers where it would definitively impact inlining - it adds them to *any* doc block that has more than one paragraph of plaintext and no other distinguishing features (members, features, errors, returns).
It may well be the case that not every last one of these *needs* to be amended in this way, but this is the broad coverage shotgun approach that demonstrates which places in the code may cause footguns with regards to automated stub insertions of members/arguments/etc, returns, or inlining order ambiguities.
Signed-off-by John Snow <[email protected]>
[...]
Quoted 9 lines
qapi/accelerator.json +0
-1@@ -29,12 +29,12 @@ # # Return information about KVM acceleration # -# Since: 0.14
qapi/accelerator.json line 40
Quoted 10 lines
qapi/accelerator.json +2
-1-# # .. qmp-example:: # # -> { "execute": "query-kvm" } # <- { "return": { "enabled": true, "present": true } } +# +# Since: 0.14 ## { 'command': 'query-kvm', 'returns': 'KvmInfo' }
Rendered output changes unexpectedly from
Command query-kvm (Since: 0.14)
Return information about KVM acceleration
Return:
KvmInfo
Example::
-> { "execute": "query-kvm" }
<- { "return": { "enabled": true, "present": true } }to
Command query-kvm (Since: 0.14)
Return information about KVM acceleration
Example::
-> { "execute": "query-kvm" }
<- { "return": { "enabled": true, "present": true } }
Return:
KvmInfoI guess the "Since:" quietly serves as separator between INTRO and DETAILS before the patch, and the patch is missing a DETAILS: line.
Several more instances follow.
[...]
Re: [PATCH 7/8] qapi: re-order 'since' sections to always be last
Quoted 69 lines · Markus Armbruster
Quoted 16 lines · John Snow
Note that with "Since" being moved to the last position, we open up a good many new cases of ambiguos intro-vs-details text which must be corrected with "Details:" tags.
This patch doesn't only add these markers where it would definitively impact inlining - it adds them to *any* doc block that has more than one paragraph of plaintext and no other distinguishing features (members, features, errors, returns).
It may well be the case that not every last one of these *needs* to be amended in this way, but this is the broad coverage shotgun approach that demonstrates which places in the code may cause footguns with regards to automated stub insertions of members/arguments/etc, returns, or inlining order ambiguities.
Signed-off-by John Snow <[email protected]>[...]
Quoted 9 lines
qapi/accelerator.json +0
-1@@ -29,12 +29,12 @@ # # Return information about KVM acceleration # -# Since: 0.14qapi/accelerator.json line 40
Quoted 10 lines
qapi/accelerator.json +2
-1-# # .. qmp-example:: # # -> { "execute": "query-kvm" } # <- { "return": { "enabled": true, "present": true } } +# +# Since: 0.14 ## { 'command': 'query-kvm', 'returns': 'KvmInfo' }Rendered output changes unexpectedly from
Command query-kvm (Since: 0.14) Return information about KVM acceleration Return: KvmInfo Example:: -> { "execute": "query-kvm" } <- { "return": { "enabled": true, "present": true } }to
Command query-kvm (Since: 0.14) Return information about KVM acceleration Example:: -> { "execute": "query-kvm" } <- { "return": { "enabled": true, "present": true } } Return: KvmInfo
Quoted 7 lines
I guess the "Since:" quietly serves as separator between INTRO and DETAILS before the patch, and the patch is missing a DETAILS: line.
Several more instances follow.
[...]
Oh, drats. I suppose my yelping tool doesn't notice this kind of change in particular.
I suppose I'll compare before/after of my .ir files and use that to identify which cases change.
Good spot.
PATCH 8/8 qapi: enforce strict positioning for "Since:" section
In reply to John Snow--- scripts/qapi/parser.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
scripts/qapi/parser.py +1 -1
@@ -550,7 +550,7 @@ def get_doc(self) -> 'QAPIDoc': def _tag_check(what: str) -> None: nonlocal last_section - if what in ('TODO', 'Since'): + if what == 'TODO': return this_section = QAPIDoc.Kind.from_string(what)
Signature · 1 line
2.53.0