qapi: enforce section ordering
v2 cover qapi: enforce section ordering
Hiya, this series is meant to accomplish mostly one thing: Enforce a stricter ordering of sections in QAPI documentation blocks.
The reason to do this is mostly for the sake of the inliner: if QAPI documentation blocks have some known, canonical order, it is easier to merge two documentation blocks together for the purposes of showing all arguments for commands/etc in a simple, flat list without needing to follow hyperlink breadcrumbs.
Another reason to do this is to simplify where we insert autogenerated documentation. If the order is enforced, then inserting "Not Documented" stubs for members and generated "Returns:" statements can have a much simpler algorithm that will always match how manually written documentation is presented, in the same order.
This is still pretty RFC quality, the tests have not been implemented and the implementation of changes in the parser are still pretty fuzzy. The main point of this series at this point in time is to review the QAPI source changes and decide if the strategy employed in fixing the section ordering is the direction we ultimately want to go in.
V2:
- Add quite a few FIXME stubs for tests
- Much more carefully delineate QAPI source changes into ones required to prevent visible changes, and ones that explictly create visible changes
- Various commit message / comment changes
- Fix heuristic for griping about Intro/Details "ambiguity" to also ignore generated "Returns" sections, which was missing before and missed quite a few cases that did impact rendered output
To verify rendering changes (or lack thereof), I used this strategy:
(1) For a reference output before a change, I ran a build:
Quoted 1 line
V=1 DEBUG=1 make -j13;
(2) Then I created some reference output for the intermediate rST debugging output files (fish syntax):
> for i in *.ir; sed -E 's|\.json:[0-9]{4}|.json:nnnn|g' $i > $i.ref; end
(3) Then after applying a patch, to check for any differences, I re-ran the build as in (1) and then:
> for i in *.ir; sed -E 's|\.json:[0-9]{4}|.json:nnnn|g' $i > $i.new; end > for i in *.ir; meld $i.ref $i.new; end
An observation: Most of the time, the Intro section is only one paragraph anyway. We might be able to save on some explicit "Details:" syntax if we just formalize the idea that the intro can only ever be at most one paragraph. I don't know if we want to do that (Do we want to keep the ability to run long in the "intro"?) - but it would cut down on quite a lot of markup that this series adds.
John Snow (10):
qapi: differentiate "intro" and "details" sections
qapi: prohibit 'details' sections between tagged sections
qapi: add "Details:" disambiguation marker
qapi: add "Details:" markers where needed
qapi: add "Details:" markers where potentially needed
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/devel/qapi-code-gen.rst | 33 +++- 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 +- qga/qapi-schema.json | 2 + scripts/qapi/parser.py | 134 ++++++++++++-- tests/qapi-schema/doc-good.json | 12 +- tests/qapi-schema/doc-good.out | 10 +- tests/qapi-schema/doc-good.txt | 18 +- tests/qapi-schema/doc-misplaced-details.err | 0 tests/qapi-schema/doc-misplaced-details.json | 3 + tests/qapi-schema/doc-misplaced-details.out | 11 ++ tests/qapi-schema/doc-missing-details.err | 0 tests/qapi-schema/doc-missing-details.json | 3 + tests/qapi-schema/doc-missing-details.out | 11 ++ tests/qapi-schema/meson.build | 2 + 44 files changed, 784 insertions(+), 519 deletions(-) create mode 100644 tests/qapi-schema/doc-misplaced-details.err create mode 100644 tests/qapi-schema/doc-misplaced-details.json create mode 100644 tests/qapi-schema/doc-misplaced-details.out create mode 100644 tests/qapi-schema/doc-missing-details.err create mode 100644 tests/qapi-schema/doc-missing-details.json create mode 100644 tests/qapi-schema/doc-missing-details.out
Signature · 1 line
2.53.0
PATCH v2 1/10 qapi: differentiate "intro" and "details" sections
This patch begins distinguishing "Plain" sections as being either "Intro" or "Details" sections for the purpose of, in the forthcoming documentation inliner, knowing when/where/how to inline those sections. i.e. "Intro" sections will not be inlined, but "Details" sections will be. The intent is for "Intro" sections to describe (briefly) only the specific entity, but for details sections to describe information in greater detail that would be relevant to include in inlined documentation.
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, as of this patch, is any plaintext section after the initial section. (It cannot appear immediately following the INTRO section, because it would then simply be part of that intro section.)
---
[Review note: .ir files remain unchanged before and after this patch, it should be completely inert with regards to the rendered output. --js]
--- 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
PATCH v2 2/10 qapi: prohibit 'details' sections between tagged sections
In reply to John SnowThis patch prohibits plain documentation sections from appearing between (most*) tagged/description sections. The two existing uses of this pattern (One in tests, one in our actual docs) are patched out.
This is being done for two main reasons:
(1) By limiting the locations where a "details" section may occur, it is easier to reason about where a details section must be placed when merging two or more documentation blocks together. This eases the logic in the forthcoming inliner significantly.
(2) It improves visual consistency in the rendered HTML output. Tagged sections and descriptions are all presented in a tabular format, so prohibiting free-form text from interleaving the table looks better.
(*"most": As of this patch, TODO and Since sections may still occur before, after, or between detail sections. These sections are removed from the flow of the document when rendered to HTML, so in effect even though we may have multiple details sections, they will be contiguous in rendered HTML output.)
---
[Review note: the output of *.ir files changes slightly, but intentionally, with this patch; the two distinct changes correlate with the edits made to the qapi .json files modified explicitly by this patch. --js]
--- docs/devel/qapi-code-gen.rst | 15 +++++++++++---- qapi/qom.json | 4 ++-- scripts/qapi/parser.py | 19 +++++++++++++++++++ tests/qapi-schema/doc-good.json | 4 ++-- tests/qapi-schema/doc-good.out | 4 ++-- tests/qapi-schema/doc-good.txt | 8 ++++---- tests/qapi-schema/doc-misplaced-details.err | 0 tests/qapi-schema/doc-misplaced-details.json | 3 +++ tests/qapi-schema/doc-misplaced-details.out | 11 +++++++++++ tests/qapi-schema/meson.build | 1 + 10 files changed, 55 insertions(+), 14 deletions(-) create mode 100644 tests/qapi-schema/doc-misplaced-details.err create mode 100644 tests/qapi-schema/doc-misplaced-details.json create mode 100644 tests/qapi-schema/doc-misplaced-details.out
docs/devel/qapi-code-gen.rst +11 -4
@@ -985,10 +985,17 @@ When documentation is required (see pragma_ 'doc-required'), every definition must have documentation. Definition documentation starts with a line naming the definition, -followed by an optional overview, a description of each argument (for -commands and events), member (for structs and unions), branch (for -alternates), or value (for enums), a description of each feature (if -any), and finally optional tagged sections. +followed by an optional overview (the "intro"), a description of each +argument (for commands and events), member (for structs and unions), +branch (for alternates), or value (for enums), a description of each +feature (if any), most optional tagged sections, plaintext detail +paragraphs, and finally the optional "Since" tagged section. + +Paragraphs following the optional overview (the "intro") may not appear +between any description or tagged section as described above. These +sections are "detail" sections and must appear at the end of the +documentation block, with the exception of "Since" or "TODO" sections +which may appear after. Descriptions start with '\@name:'. The description text must be indented like this::
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 +19 -0
@@ -545,6 +545,21 @@ def get_doc(self) -> 'QAPIDoc': self.accept(False) line = self.get_doc_line() have_tagged = False + no_more_tags = False + + def _tag_check(this: Union['QAPIDoc.Kind', str]) -> None: + if isinstance(this, str): + this = QAPIDoc.Kind.from_string(this) + if this in (QAPIDoc.Kind.TODO, QAPIDoc.Kind.SINCE): + return + + if no_more_tags: + raise QAPIParseError( + self, + f"'{this}' 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 +573,7 @@ def get_doc(self) -> 'QAPIDoc': if doc.features: raise QAPIParseError( self, "duplicated 'Features:' line") + _tag_check(QAPIDoc.Kind.FEATURE) self.accept(False) line = self.get_doc_line() while line == '':
@@ -621,6 +637,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 +649,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
tests/qapi-schema/doc-misplaced-details.err new file +0 -0
tests/qapi-schema/doc-misplaced-details.json new file +3 -0
@@ -0,0 +1,3 @@ +# FIXME / TODO +# This test should test for the error message when we misplace details +# sections interleaved between descriptions/tagged sections.
tests/qapi-schema/doc-misplaced-details.out new file +11 -0
@@ -0,0 +1,11 @@ +module ./builtin +object q_empty +enum QType + member none + member qnull + member qnum + member qstring + member qdict + member qlist + member qbool +module doc-misplaced-details.json
tests/qapi-schema/meson.build +1 -0
@@ -83,6 +83,7 @@ schemas = [ 'doc-invalid-section.json', 'doc-invalid-start.json', 'doc-long-line.json', + 'doc-misplaced-details.json', 'doc-missing-colon.json', 'doc-missing-expr.json', 'doc-missing-space.json',
Signature · 1 line
2.53.0
PATCH v2 3/10 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 of documentation inlined into another documentation block will be omitted, which may lead to unintentional omissions of details in the rendered output.
When the delineation between "intro" and "details" is not clear because there is no intervening description/tagged sections, 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.
Replace existing uses of "TODO:" hacks to achieve this effect with the canonical marker.
---
[Review note: all *.ir files are completely unchanged before and after this patch. --js]
--- docs/devel/qapi-code-gen.rst | 18 ++++++++++++++++++ qapi/machine.json | 2 +- qapi/migration.json | 4 ++-- qapi/net.json | 2 +- qapi/yank.json | 2 +- scripts/qapi/parser.py | 8 ++++++++ 6 files changed, 31 insertions(+), 5 deletions(-)
docs/devel/qapi-code-gen.rst +18 -0
@@ -1048,6 +1048,24 @@ definition. QMP). In other sections, the text is formatted, and rST markup can be used. +In cases where documentation consists of several paragraphs of text with +no intervening sections to delineate them, it may become necessary to +explicitly declare the start of the details section by using a +"Details:" marker. For example:: + + ## + # @foobar + # + # foobar is an example definition. + # + # Details: + # + # Since there are no other sections in this documentation, the above + # "Details:" marker is required to mark this and subsequent paragraphs + # as the "Details" section. Any automatically generated documentation + # sections will be inserted above this point instead of below. + ## + QMP Examples can be added by using the ``.. qmp-example::`` directive. In its simplest form, this can be used to contain a single QMP code block which accepts standard JSON syntax with additional server
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 +2 -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:: #
@@ -1687,7 +1687,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/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/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
@@ -590,6 +590,14 @@ def _tag_check(this: Union['QAPIDoc.Kind', 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
PATCH v2 4/10 qapi: add "Details:" markers where needed
In reply to John SnowAdd additional "Details:" markers in places where doing so *currently* impacts the rendered output order of documentation sections.
There are two cases where this is done:
(1) Where we insert stub/autogenerated documentation for members/args/etc and return information is dependent on the intro-details split location. Adding a "Details:" marker facilitates inserting this information in the middle of the documentation block instead of at the end.
These are locations where we likely SHOULD have been using the "TODO:" hack which was formalized in the previous commit, but had not been.
(2) Cases where "Since:" currently behaves as the Intro/Details separation point, but in the wrong location. Since this edit changes the output, these changes are included in this patch as well. These locations are for HV_BALLOON_STATUS_REPORT, query-gic-capabilities, and query-sev.
---
[Review note: this patch DOES change the output of the *.ir files, but intentionally for these locations. --js]
--- qapi/block-core.json | 3 +++ qapi/machine.json | 2 ++ qapi/misc-arm.json | 2 ++ qapi/misc-i386.json | 2 ++ qapi/qom.json | 4 ++++ qga/qapi-schema.json | 2 ++ 6 files changed, 15 insertions(+)
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 +2 -0
@@ -1223,6 +1223,8 @@ # Emitted when the hv-balloon driver receives a "STATUS" message from # the guest. # +# Details: +# # .. note:: This event is rate-limited. # # Since: 8.2
qapi/misc-arm.json +2 -0
@@ -33,6 +33,8 @@ # 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. #
qapi/misc-i386.json +2 -0
@@ -127,6 +127,8 @@ # # 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.
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
qga/qapi-schema.json +2 -0
@@ -420,6 +420,8 @@ # # Get guest fsfreeze state. # +# Details: +# # .. note:: This may fail to properly report the current state as a # result of some other guest processes having issued an fs # freeze/thaw.
Signature · 1 line
2.53.0
PATCH v2 5/10 qapi: add "Details:" markers where potentially needed
In reply to John SnowThere are several locations within the QAPI source that are classified as "Intro" text, even though semantically this is not true. Altering these sections with an explicit Details: marker currently yields no difference to rendered output. In the future, the inliner and/or the addition of new stub sections *may* make these distinctions important.
These locations were identified using a heuristic patch to the QAPI doc parser to emit a warning for Intro sections consisting of two or more paragraphs without any other explicit section present in the source code.
---
[Review note: this patch does not change the *.ir output at all; there is no visible difference whatsoever. The point of this patch is solely to prevent yelping by the heuristic checker. It may or may not become relevant later once the inliner is merged, I did not audit that far - neither did I spend time attempting to improve the heuristic yelper, believing "KISS". --js]
--- qapi/migration.json | 4 ++++ 1 file changed, 4 insertions(+)
qapi/migration.json +4 -0
@@ -1651,6 +1651,8 @@ # # Xen uses this command to notify replication to trigger a checkpoint. # +# Details: +# # .. qmp-example:: # # -> { "execute": "xen-colo-do-checkpoint" }
@@ -1724,6 +1726,8 @@ # # Pause a migration. Currently it only supports postcopy. # +# Details: +# # .. qmp-example:: # # -> { "execute": "migrate-pause" }
Signature · 1 line
2.53.0
PATCH v2 6/10 qapi: detect potentially semantically ambiguous intro paragraphs
In reply to John SnowCajole the QAPI Doc parser into yelping if a QAPI Doc Block contains two or more paragraphs 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.
Such locations do not currently *guarantee* a difference to rendered manual output, but later changes to the documentation generator that may include additional auto-generated sections, and complexities from the inliner, may increase the odds that these locations are suspect and will need to be explicitly delineated.
---
[Review notes: no changes to *.ir files. --js]
--- scripts/qapi/parser.py | 49 ++++++++++++++++++++++ tests/qapi-schema/doc-missing-details.err | 0 tests/qapi-schema/doc-missing-details.json | 3 ++ tests/qapi-schema/doc-missing-details.out | 11 +++++ tests/qapi-schema/meson.build | 1 + 5 files changed, 64 insertions(+) create mode 100644 tests/qapi-schema/doc-missing-details.err create mode 100644 tests/qapi-schema/doc-missing-details.json create mode 100644 tests/qapi-schema/doc-missing-details.out
scripts/qapi/parser.py +49 -0
@@ -32,6 +32,8 @@ from .source import QAPISourceInfo +# pylint: disable=too-many-lines + if TYPE_CHECKING: # pylint: disable=cyclic-import # TODO: Remove cycle. [schema -> expr -> parser -> schema]
@@ -962,3 +964,50 @@ 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")) + else: + if section.kind == QAPIDoc.Kind.MEMBER and not section.text: + pass + elif section.kind == QAPIDoc.Kind.RETURNS and not section.text: + pass + else: + # 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." + )
tests/qapi-schema/doc-missing-details.err new file +0 -0
tests/qapi-schema/doc-missing-details.json new file +3 -0
@@ -0,0 +1,3 @@ +# TODO / FIXME +# This test intentionally triggers the parser warning +# suggesting we use the Details: marker.
tests/qapi-schema/doc-missing-details.out new file +11 -0
@@ -0,0 +1,11 @@ +module ./builtin +object q_empty +enum QType + member none + member qnull + member qnum + member qstring + member qdict + member qlist + member qbool +module doc-missing-details.json
tests/qapi-schema/meson.build +1 -0
@@ -85,6 +85,7 @@ schemas = [ 'doc-long-line.json', 'doc-misplaced-details.json', 'doc-missing-colon.json', + 'doc-missing-details.json', 'doc-missing-expr.json', 'doc-missing-space.json', 'doc-missing.json',
Signature · 1 line
2.53.0
PATCH v2 7/10 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 a subsequent patch, as it is a much larger commit.
---
[Many changes to the *.ir files, generally :feat: lines moving lower. All changes are just relative re-orderings of the field list section of the output, and all of these changes are intentional. --js]
--- 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
PATCH v2 8/10 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.
---
[Review note: No changes to *.ir files. --js]
--- scripts/qapi/parser.py | 55 ++++++++++++++++++++++++++---------------- 1 file changed, 34 insertions(+), 21 deletions(-)
scripts/qapi/parser.py +34 -21
@@ -547,22 +547,28 @@ def get_doc(self) -> 'QAPIDoc': self.accept(False) line = self.get_doc_line() have_tagged = False - no_more_tags = False + last_ordered_section = QAPIDoc.Kind.INTRO def _tag_check(this: Union['QAPIDoc.Kind', str]) -> None: + nonlocal last_ordered_section if isinstance(this, str): this = QAPIDoc.Kind.from_string(this) + if this in (QAPIDoc.Kind.TODO, QAPIDoc.Kind.SINCE): return - if no_more_tags: + if this.value < last_ordered_section.value: raise QAPIParseError( self, - f"'{this}' section cannot appear after plain " - "paragraphs that follow other tagged sections\n" - "Move this section up above the plain paragraph(s)." + f"'{this}' section cannot appear after " + f"'{last_ordered_section}' 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_ordered_section = this + while line is not None: # Blank lines while line == '':
@@ -593,7 +599,7 @@ def _tag_check(this: Union['QAPIDoc.Kind', str]) -> None: self, 'feature descriptions expected') have_tagged = True elif line == 'Details:': - _tag_check("Details") + _tag_check(QAPIDoc.Kind.DETAILS) self.accept(False) line = self.get_doc_line() while line == '':
@@ -602,6 +608,7 @@ def _tag_check(this: Union['QAPIDoc.Kind', str]) -> None: have_tagged = True elif match := self._match_at_name_colon(line): # description + _tag_check(QAPIDoc.Kind.MEMBER) if have_tagged: raise QAPIParseError( self,
@@ -658,14 +665,16 @@ def _tag_check(this: Union['QAPIDoc.Kind', 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 - doc.ensure_untagged_section(self.info, intro) + # Paragraphs appearing before any other sections are + # "intro" paragraphs. Any appearing after are + # "details" paragraphs. + this_section = ( + QAPIDoc.Kind.DETAILS + if have_tagged + else QAPIDoc.Kind.INTRO + ) + _tag_check(this_section) + doc.ensure_untagged_section(self.info, this_section) doc.append_line(line) line = self.get_doc_paragraph(doc) else:
@@ -707,14 +716,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':
@@ -793,9 +805,10 @@ def end(self) -> None: def ensure_untagged_section( self, info: QAPISourceInfo, - intro: bool = True, + kind: Optional['QAPIDoc.Kind'] = None, ) -> None: - kind = QAPIDoc.Kind.INTRO if intro else QAPIDoc.Kind.DETAILS + if kind is None: + kind = QAPIDoc.Kind.INTRO if self.all_sections and self.all_sections[-1].kind == kind: # extend current section
Signature · 1 line
2.53.0
PATCH v2 9/10 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.
These markers are added to this patch in two cases:
(1) Where failing to add it would immediately (i.e. without the future inliner feature) cause a change to the rendered output
(2) Where failing to add it causes new warning message yelps.
These cases are not presently delineated.
---
[Review notes: This patch produces no changes to the *.ir files! --js]
--- 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 | 84 +++++++++++++--------- qapi/migration.json | 94 +++++++++++++----------- qapi/misc-arm.json | 4 +- qapi/misc-i386.json | 38 +++++----- 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, 472 insertions(+), 383 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 +5 -3
@@ -29,12 +29,14 @@ # # Return information about KVM acceleration # -# Since: 0.14 +# Details: # # .. qmp-example:: # # -> { "execute": "query-kvm" } # <- { "return": { "enabled": true, "present": true } } +# +# Since: 0.14 ## { 'command': 'query-kvm', 'returns': 'KvmInfo' }
@@ -101,11 +103,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 +20 -16
@@ -38,7 +38,7 @@ # # Return information about current character devices. # -# Since: 0.14 +# Details: # # .. qmp-example:: #
@@ -62,6 +62,8 @@ # } # ] # } +# +# Since: 0.14 ## { 'command': 'query-chardev', 'returns': ['ChardevInfo'], 'allow-preconfig': true }
@@ -82,7 +84,7 @@ # # Return information about character device backends. # -# Since: 2.0 +# Details: # # .. qmp-example:: #
@@ -103,6 +105,8 @@ # } # ] # } +# +# Since: 2.0 ## { 'command': 'query-chardev-backends', 'returns': ['ChardevBackendInfo'] }
@@ -137,8 +141,6 @@ # - data itself is always Unicode regardless of format, like any # other string. # -# Since: 1.4 -# # .. qmp-example:: # # -> { "execute": "ringbuf-write",
@@ -146,6 +148,8 @@ # "data": "abcdefgh", # "format": "utf8" } } # <- { "return": {} } +# +# Since: 1.4 ## { 'command': 'ringbuf-write', 'data': { 'device': 'str',
@@ -173,8 +177,6 @@ # # Returns: data read from the device # -# Since: 1.4 -# # .. qmp-example:: # # -> { "execute": "ringbuf-read",
@@ -182,6 +184,8 @@ # "size": 1000, # "format": "utf8" } } # <- { "return": "abcdefgh" } +# +# Since: 1.4 ## { 'command': 'ringbuf-read', 'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'},
@@ -761,8 +765,6 @@ # # @backend: backend type and parameters # -# Since: 1.4 -# # .. qmp-example:: # # -> { "execute" : "chardev-add",
@@ -784,6 +786,8 @@ # "arguments" : { "id" : "baz", # "backend" : { "type" : "pty", "data" : {} } } } # <- { "return": { "pty" : "/dev/pty/42" } } +# +# Since: 1.4 ## { 'command': 'chardev-add', 'data': { 'id': 'str',
@@ -799,8 +803,6 @@ # # @backend: new backend type and parameters # -# Since: 2.10 -# # .. qmp-example:: # # -> { "execute" : "chardev-change",
@@ -825,6 +827,8 @@ # "server" : true, # "wait" : false }}}} # <- {"return": {}} +# +# Since: 2.10 ## { 'command': 'chardev-change', 'data': { 'id': 'str',
@@ -838,12 +842,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 +859,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 +880,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 -34
326 lines not on this page · raw message
qapi/migration.json +54 -40
356 lines not on this page · raw message
qapi/misc-arm.json +2 -2
@@ -38,13 +38,13 @@ # 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 +22 -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' }
@@ -133,14 +135,14 @@ # @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' }
@@ -171,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' }
@@ -216,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' }
@@ -282,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' },
@@ -338,7 +340,7 @@ # # Return information about configured SGX capabilities of guest # -# Since: 6.2 +# Details: # # .. qmp-example:: #
@@ -347,6 +349,8 @@ # "flc": true, # "sections": [{"node": 0, "size": 67108864}, # {"node": 1, "size": 29360128}]} } +# +# Since: 6.2 ## { 'command': 'query-sgx', 'returns': 'SgxInfo' }
@@ -355,7 +359,7 @@ # # Return information about SGX capabilities of host # -# Since: 6.2 +# Details: # # .. qmp-example:: #
@@ -364,6 +368,8 @@ # "flc": true, # "section" : [{"node": 0, "size": 67108864}, # {"node": 1, "size": 29360128}]} } +# +# Since: 6.2 ## { 'command': 'query-sgx-capabilities', 'returns': 'SgxInfo' }
@@ -426,8 +432,6 @@ # # Returns: list of open event channel ports. # -# Since: 8.0 -# # .. qmp-example:: # # -> { "execute": "xen-event-list" }
@@ -452,6 +456,8 @@ # } # ] # } +# +# Since: 8.0 ## { 'command': 'xen-event-list', 'returns': ['EvtchnInfo'] }
@@ -463,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 +36 -28
247 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 +9 -3
@@ -29,12 +29,14 @@ # # Return a list of supported TPM models # -# Since: 1.5 +# Details: # # .. 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 +60,14 @@ # # Return a list of supported TPM types # -# Since: 1.5 +# Details: # # .. qmp-example:: # # -> { "execute": "query-tpm-types" } # <- { "return": [ "passthrough", "emulator" ] } +# +# Since: 1.5 ## { 'command': 'query-tpm-types', 'returns': ['TpmType'], 'if': 'CONFIG_TPM' }
@@ -164,7 +168,7 @@ # # Return information about the TPM device # -# Since: 1.5 +# Details: # # .. qmp-example:: #
@@ -183,6 +187,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 +43 -33
95 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.
PATCH v2 10/10 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
@@ -554,7 +554,7 @@ def _tag_check(this: Union['QAPIDoc.Kind', str]) -> None: if isinstance(this, str): this = QAPIDoc.Kind.from_string(this) - if this in (QAPIDoc.Kind.TODO, QAPIDoc.Kind.SINCE): + if this == QAPIDoc.Kind.TODO: return if this.value < last_ordered_section.value:
Signature · 1 line
2.53.0
Quoted 45 lines · John Snow
Hiya, this series is meant to accomplish mostly one thing: Enforce a stricter ordering of sections in QAPI documentation blocks.
The reason to do this is mostly for the sake of the inliner: if QAPI documentation blocks have some known, canonical order, it is easier to merge two documentation blocks together for the purposes of showing all arguments for commands/etc in a simple, flat list without needing to follow hyperlink breadcrumbs.
Another reason to do this is to simplify where we insert autogenerated documentation. If the order is enforced, then inserting "Not Documented" stubs for members and generated "Returns:" statements can have a much simpler algorithm that will always match how manually written documentation is presented, in the same order.
This is still pretty RFC quality, the tests have not been implemented and the implementation of changes in the parser are still pretty fuzzy. The main point of this series at this point in time is to review the QAPI source changes and decide if the strategy employed in fixing the section ordering is the direction we ultimately want to go in.
V2:
- Add quite a few FIXME stubs for tests
- Much more carefully delineate QAPI source changes into ones required to prevent visible changes, and ones that explictly create visible changes
- Various commit message / comment changes
- Fix heuristic for griping about Intro/Details "ambiguity" to also ignore generated "Returns" sections, which was missing before and missed quite a few cases that did impact rendered outputTo verify rendering changes (or lack thereof), I used this strategy:
(1) For a reference output before a change, I ran a build:
Quoted 1 line
V=1 DEBUG=1 make -j13;
(2) Then I created some reference output for the intermediate rST debugging output files (fish syntax):
> for i in *.ir; sed -E 's|\.json:[0-9]{4}|.json:nnnn|g' $i > $i.ref; end(3) Then after applying a patch, to check for any differences, I re-ran the build as in (1) and then:
> for i in *.ir; sed -E 's|\.json:[0-9]{4}|.json:nnnn|g' $i > $i.new; end > for i in *.ir; meld $i.ref $i.new; end
Quoted 6 lines
An observation: Most of the time, the Intro section is only one paragraph anyway. We might be able to save on some explicit "Details:" syntax if we just formalize the idea that the intro can only ever be at most one paragraph. I don't know if we want to do that (Do we want to keep the ability to run long in the "intro"?) - but it would cut down on quite a lot of markup that this series adds.
The series adds 59 "Details:" markers to ~1150 doc comments, i.e. about one in twenty doc comments needs one.
I can see several ways to skin this cat:
1. Intro ends when something else begins
Intro can be any number of paragraphs.
When intro is followed by details, we need a way to mark the boundary. That's your "Details:" marker. Relatively rare.
Drawback: since you need "Details:" only rarely, it is easy to forget. Details are then mistaken for intro or the other way round. The inliner will lose details / fail to lose intro.
This is what your series gives us.
2. Intro ends after the first paragraph if we have one.
Intro can be empty or one paragraph.
When empty intro is followed by details, we need a way to mark the boundary, such as "Details:". This is quite rare.
Drawback: "at most one paragraph" is not obvious and easy to forget. Extra intro paragraphs end up in details then, where the inliner will copy them.
Drawback: since you need "Details:" almost never, it is easy to forget. The first paragraph of Details is mistaken for intro then. The inliner will lose it.
3. Make the end of intro syntactically obvious always
3a. Require the "Details:" line
Intro can be any number of paragraphs.
Drawback: the syntax is rather clumsy. ~270 doc comments have details, and every one of them needs a "Details:" line.
Drawback: you can still forget the "Details:" line. If you do, the entire details will be mistaken for intro, and the inliner will lose them.
3b. Require a "Details:" tag
Like 3a, but with slightly less clumsy syntax. Instead of
# @Frob:
#
# Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do # eiusmod tempor incididunt ut labore et dolore magna aliqua. #
# Details:
#
# Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris # nisi ut aliquip ex ea commodo consequat.
#
# Duis aute irure dolor in reprehenderit in voluptate velit esse # cillum dolore eu fugiat nulla pariatur.
we get
# @Frob:
#
# Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do # eiusmod tempor incididunt ut labore et dolore magna aliqua. #
# Details: Ut enim ad minim veniam, quis nostrud exercitation ullamco
# laboris nisi ut aliquip ex ea commodo consequat.
#
# Duis aute irure dolor in reprehenderit in voluptate velit esse
# cillum dolore eu fugiat nulla pariatur.
Drawback: the syntax is still clumsy. ~270 doc comments have details, and every one of them needs a "Details:" tag and be reindented.
Drawback: if you forget to tag details, they get mistaken for intro, and the inliner will lose them. Less likely than with 3a?
3c. Indent intro like descriptions and tagged sections.
Like so:
# @Frob:
# Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
# eiusmod tempor incididunt ut labore et dolore magna aliqua.
#
# Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris # nisi ut aliquip ex ea commodo consequat.
#
# Duis aute irure dolor in reprehenderit in voluptate velit esse # cillum dolore eu fugiat nulla pariatur.
Drawback: all the intros get reindented.
Drawback: if you format intro the old way, it gets mistaken for details, and the inliner will fail to lose it. Likely to happen initially, but hopefully becomes unlikely once people got used to it.
Anything else?
3d. Both 3b and 3c
Intros and details written the old way get rejected.
Drawback: all intros and all details need to be reindented.
Anything else?
Thoughts?