From 66c83cdd91c07575ebf30bb45da8cc5df8041c29 Mon Sep 17 00:00:00 2001 From: John Snow Date: Wed, 18 Jun 2025 12:53:49 -0400 Subject: [PATCH 01/29] docs/sphinx: adjust qapidoc to cope with same-line error sections Without this, the line the new QAPI doc generator chokes on # Errors: some in doc-good.json. We still use the old doc generator for the tests, but we're about to correct that. Signed-off-by: John Snow Message-ID: <20250618165353.1980365-2-jsnow@redhat.com> Acked-by: Markus Armbruster Fixes: e9fbf1a0c6c2 (docs/qapidoc: add visit_errors() method) [Amend commit message to point to reproducer, and add Fixes:] Signed-off-by: Markus Armbruster --- docs/sphinx/qapidoc.py | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 8011ac9efa..5374dee8fa 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -267,10 +267,14 @@ def visit_returns(self, section: QAPIDoc.Section) -> None: self.add_field("return", typ, section.text, section.info) def visit_errors(self, section: QAPIDoc.Section) -> None: - # FIXME: the formatting for errors may be inconsistent and may - # or may not require different newline placement to ensure - # proper rendering as a nested list. - self.add_lines(f":error:\n{section.text}", section.info) + # If the section text does not start with a space, it means text + # began on the same line as the "Error:" string and we should + # not insert a newline in this case. + if section.text[0].isspace(): + text = f":error:\n{section.text}" + else: + text = f":error: {section.text}" + self.add_lines(text, section.info) def preamble(self, ent: QAPISchemaDefinition) -> None: """ From e56c683bae9d1dc1b637029a0595225499ef7248 Mon Sep 17 00:00:00 2001 From: John Snow Date: Wed, 18 Jun 2025 12:53:50 -0400 Subject: [PATCH 02/29] docs/sphinx: parse @references in freeform text Oversight in the new qapidoc transmogrifier: @references in freeform documentation blocks were not being transformed to literals. This fixes that, and the next patch ensures that we're testing for this O:-) Signed-off-by: John Snow Message-ID: <20250618165353.1980365-3-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/sphinx/qapidoc.py | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 5374dee8fa..adc14ade45 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -218,6 +218,11 @@ def generate_field( typ = self.format_type(member) self.add_field(kind, member.name, body, info, typ) + @staticmethod + def reformat_arobase(text: str) -> str: + """ reformats @var to ``var`` """ + return re.sub(r"@([\w-]+)", r"``\1``", text) + # Transmogrification helpers def visit_paragraph(self, section: QAPIDoc.Section) -> None: @@ -361,8 +366,7 @@ def visit_sections(self, ent: QAPISchemaDefinition) -> None: # Add sections in source order: for i, section in enumerate(sections): - # @var is translated to ``var``: - section.text = re.sub(r"@([\w-]+)", r"``\1``", section.text) + section.text = self.reformat_arobase(section.text) if section.kind == QAPIDoc.Kind.PLAIN: self.visit_paragraph(section) @@ -405,7 +409,7 @@ def visit_freeform(self, doc: QAPIDoc) -> None: assert len(doc.all_sections) == 1, doc.all_sections body = doc.all_sections[0] - text = body.text + text = self.reformat_arobase(body.text) info = doc.info if re.match(r"=+ ", text): From 8d789c8cdb8de2cae39f217b6c9607ac9c036c8c Mon Sep 17 00:00:00 2001 From: John Snow Date: Wed, 18 Jun 2025 12:53:51 -0400 Subject: [PATCH 03/29] docs/sphinx: remove legacy QAPI manual generator Thanks for your service! Remove the old qapidoc and the option to enable the transmogrifier, leaving the "transmogrifier" as the ONLY qapi doc generator. This in effect also converts the QAPI test to use the new documentation generator, too. Update doc-good.txt output to match the new doc generator, which I should've done exactly when we switched over to the transmogrifier, but, uhh, oops! Notes on the new format: 1. per-member IFCOND documentation is missing. Known issue. 2. Freeform documentation without a header is now copied through into the output. This is a bug fix. Signed-off-by: John Snow Message-ID: <20250618165353.1980365-4-jsnow@redhat.com> Acked-by: Markus Armbruster Fixes: b61a4eb3f32 (docs/qapidoc: support header-less freeform sections) [Tweak commit message to say it's a bug fix, add Fixes:] Signed-off-by: Markus Armbruster --- docs/interop/qemu-ga-ref.rst | 1 - docs/interop/qemu-qmp-ref.rst | 1 - docs/interop/qemu-storage-daemon-qmp-ref.rst | 1 - docs/sphinx/qapidoc.py | 25 +- docs/sphinx/qapidoc_legacy.py | 440 ------------------- python/tests/qapi-isort.sh | 2 +- tests/qapi-schema/doc-good.txt | 274 ++++-------- 7 files changed, 88 insertions(+), 656 deletions(-) delete mode 100644 docs/sphinx/qapidoc_legacy.py diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst index 25f6e24b03..ea6652ae43 100644 --- a/docs/interop/qemu-ga-ref.rst +++ b/docs/interop/qemu-ga-ref.rst @@ -2,5 +2,4 @@ QEMU Guest Agent Protocol Reference =================================== .. qapi-doc:: qga/qapi-schema.json - :transmogrify: :namespace: QGA diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst index 3bc1ca12b1..f0ce39ad67 100644 --- a/docs/interop/qemu-qmp-ref.rst +++ b/docs/interop/qemu-qmp-ref.rst @@ -7,5 +7,4 @@ QEMU QMP Reference Manual :local: .. qapi-doc:: qapi/qapi-schema.json - :transmogrify: :namespace: QMP diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst index dc7bde262a..4dbb6a2cc8 100644 --- a/docs/interop/qemu-storage-daemon-qmp-ref.rst +++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst @@ -5,5 +5,4 @@ QEMU Storage Daemon QMP Reference Manual :local: .. qapi-doc:: storage-daemon/qapi/qapi-schema.json - :transmogrify: :namespace: QSD diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index adc14ade45..d5d2b5eeb5 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -64,8 +64,6 @@ from sphinx.util.docutils import SphinxDirective, switch_source_input from sphinx.util.nodes import nested_parse_with_titles -from qapidoc_legacy import QAPISchemaGenRSTVisitor # type: ignore - if TYPE_CHECKING: from typing import ( @@ -512,15 +510,9 @@ class QAPIDocDirective(NestedDirective): option_spec = { "qapifile": directives.unchanged_required, "namespace": directives.unchanged, - "transmogrify": directives.flag, } has_content = False - def new_serialno(self) -> str: - """Return a unique new ID string suitable for use as a node's ID""" - env = self.state.document.settings.env - return "qapidoc-%d" % env.new_serialno("qapidoc") - def transmogrify(self, schema: QAPISchema) -> nodes.Element: logger.info("Transmogrifying QAPI to rST ...") vis = Transmogrifier() @@ -598,21 +590,10 @@ def write_intermediate(self, content: StringList, filename: str) -> None: outfile.write(f" {rcol}") outfile.write("\n") - def legacy(self, schema: QAPISchema) -> nodes.Element: - vis = QAPISchemaGenRSTVisitor(self) - vis.visit_begin(schema) - for doc in schema.docs: - if doc.symbol: - vis.symbol(doc, schema.lookup_entity(doc.symbol)) - else: - vis.freeform(doc) - return vis.get_document_node() # type: ignore - def run(self) -> Sequence[nodes.Node]: env = self.state.document.settings.env qapifile = env.config.qapidoc_srctree + "/" + self.arguments[0] qapidir = os.path.dirname(qapifile) - transmogrify = "transmogrify" in self.options try: schema = QAPISchema(qapifile) @@ -625,11 +606,7 @@ def run(self) -> Sequence[nodes.Node]: # so they are displayed nicely to the user raise ExtensionError(str(err)) from err - if transmogrify: - contentnode = self.transmogrify(schema) - else: - contentnode = self.legacy(schema) - + contentnode = self.transmogrify(schema) return contentnode.children diff --git a/docs/sphinx/qapidoc_legacy.py b/docs/sphinx/qapidoc_legacy.py deleted file mode 100644 index 13520f4c26..0000000000 --- a/docs/sphinx/qapidoc_legacy.py +++ /dev/null @@ -1,440 +0,0 @@ -# coding=utf-8 -# type: ignore -# -# QEMU qapidoc QAPI file parsing extension -# -# Copyright (c) 2020 Linaro -# -# This work is licensed under the terms of the GNU GPLv2 or later. -# See the COPYING file in the top-level directory. - -""" -qapidoc is a Sphinx extension that implements the qapi-doc directive - -The purpose of this extension is to read the documentation comments -in QAPI schema files, and insert them all into the current document. - -It implements one new rST directive, "qapi-doc::". -Each qapi-doc:: directive takes one argument, which is the -pathname of the schema file to process, relative to the source tree. - -The docs/conf.py file must set the qapidoc_srctree config value to -the root of the QEMU source tree. - -The Sphinx documentation on writing extensions is at: -https://www.sphinx-doc.org/en/master/development/index.html -""" - -import re -import textwrap - -from docutils import nodes -from docutils.statemachine import ViewList -from qapi.error import QAPISemError -from qapi.gen import QAPISchemaVisitor -from qapi.parser import QAPIDoc - - -def dedent(text: str) -> str: - # Adjust indentation to make description text parse as paragraph. - - lines = text.splitlines(True) - if re.match(r"\s+", lines[0]): - # First line is indented; description started on the line after - # the name. dedent the whole block. - return textwrap.dedent(text) - - # Descr started on same line. Dedent line 2+. - return lines[0] + textwrap.dedent("".join(lines[1:])) - - -class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): - """A QAPI schema visitor which generates docutils/Sphinx nodes - - This class builds up a tree of docutils/Sphinx nodes corresponding - to documentation for the various QAPI objects. To use it, first - create a QAPISchemaGenRSTVisitor object, and call its - visit_begin() method. Then you can call one of the two methods - 'freeform' (to add documentation for a freeform documentation - chunk) or 'symbol' (to add documentation for a QAPI symbol). These - will cause the visitor to build up the tree of document - nodes. Once you've added all the documentation via 'freeform' and - 'symbol' method calls, you can call 'get_document_nodes' to get - the final list of document nodes (in a form suitable for returning - from a Sphinx directive's 'run' method). - """ - def __init__(self, sphinx_directive): - self._cur_doc = None - self._sphinx_directive = sphinx_directive - self._top_node = nodes.section() - self._active_headings = [self._top_node] - - def _make_dlitem(self, term, defn): - """Return a dlitem node with the specified term and definition. - - term should be a list of Text and literal nodes. - defn should be one of: - - a string, which will be handed to _parse_text_into_node - - a list of Text and literal nodes, which will be put into - a paragraph node - """ - dlitem = nodes.definition_list_item() - dlterm = nodes.term('', '', *term) - dlitem += dlterm - if defn: - dldef = nodes.definition() - if isinstance(defn, list): - dldef += nodes.paragraph('', '', *defn) - else: - self._parse_text_into_node(defn, dldef) - dlitem += dldef - return dlitem - - def _make_section(self, title): - """Return a section node with optional title""" - section = nodes.section(ids=[self._sphinx_directive.new_serialno()]) - if title: - section += nodes.title(title, title) - return section - - def _nodes_for_ifcond(self, ifcond, with_if=True): - """Return list of Text, literal nodes for the ifcond - - Return a list which gives text like ' (If: condition)'. - If with_if is False, we don't return the "(If: " and ")". - """ - - doc = ifcond.docgen() - if not doc: - return [] - doc = nodes.literal('', doc) - if not with_if: - return [doc] - - nodelist = [nodes.Text(' ('), nodes.strong('', 'If: ')] - nodelist.append(doc) - nodelist.append(nodes.Text(')')) - return nodelist - - def _nodes_for_one_member(self, member): - """Return list of Text, literal nodes for this member - - Return a list of doctree nodes which give text like - 'name: type (optional) (If: ...)' suitable for use as the - 'term' part of a definition list item. - """ - term = [nodes.literal('', member.name)] - if member.type.doc_type(): - term.append(nodes.Text(': ')) - term.append(nodes.literal('', member.type.doc_type())) - if member.optional: - term.append(nodes.Text(' (optional)')) - if member.ifcond.is_present(): - term.extend(self._nodes_for_ifcond(member.ifcond)) - return term - - def _nodes_for_variant_when(self, branches, variant): - """Return list of Text, literal nodes for variant 'when' clause - - Return a list of doctree nodes which give text like - 'when tagname is variant (If: ...)' suitable for use in - the 'branches' part of a definition list. - """ - term = [nodes.Text(' when '), - nodes.literal('', branches.tag_member.name), - nodes.Text(' is '), - nodes.literal('', '"%s"' % variant.name)] - if variant.ifcond.is_present(): - term.extend(self._nodes_for_ifcond(variant.ifcond)) - return term - - def _nodes_for_members(self, doc, what, base=None, branches=None): - """Return list of doctree nodes for the table of members""" - dlnode = nodes.definition_list() - for section in doc.args.values(): - term = self._nodes_for_one_member(section.member) - # TODO drop fallbacks when undocumented members are outlawed - if section.text: - defn = dedent(section.text) - else: - defn = [nodes.Text('Not documented')] - - dlnode += self._make_dlitem(term, defn) - - if base: - dlnode += self._make_dlitem([nodes.Text('The members of '), - nodes.literal('', base.doc_type())], - None) - - if branches: - for v in branches.variants: - if v.type.name == 'q_empty': - continue - assert not v.type.is_implicit() - term = [nodes.Text('The members of '), - nodes.literal('', v.type.doc_type())] - term.extend(self._nodes_for_variant_when(branches, v)) - dlnode += self._make_dlitem(term, None) - - if not dlnode.children: - return [] - - section = self._make_section(what) - section += dlnode - return [section] - - def _nodes_for_enum_values(self, doc): - """Return list of doctree nodes for the table of enum values""" - seen_item = False - dlnode = nodes.definition_list() - for section in doc.args.values(): - termtext = [nodes.literal('', section.member.name)] - if section.member.ifcond.is_present(): - termtext.extend(self._nodes_for_ifcond(section.member.ifcond)) - # TODO drop fallbacks when undocumented members are outlawed - if section.text: - defn = dedent(section.text) - else: - defn = [nodes.Text('Not documented')] - - dlnode += self._make_dlitem(termtext, defn) - seen_item = True - - if not seen_item: - return [] - - section = self._make_section('Values') - section += dlnode - return [section] - - def _nodes_for_arguments(self, doc, arg_type): - """Return list of doctree nodes for the arguments section""" - if arg_type and not arg_type.is_implicit(): - assert not doc.args - section = self._make_section('Arguments') - dlnode = nodes.definition_list() - dlnode += self._make_dlitem( - [nodes.Text('The members of '), - nodes.literal('', arg_type.name)], - None) - section += dlnode - return [section] - - return self._nodes_for_members(doc, 'Arguments') - - def _nodes_for_features(self, doc): - """Return list of doctree nodes for the table of features""" - seen_item = False - dlnode = nodes.definition_list() - for section in doc.features.values(): - dlnode += self._make_dlitem( - [nodes.literal('', section.member.name)], dedent(section.text)) - seen_item = True - - if not seen_item: - return [] - - section = self._make_section('Features') - section += dlnode - return [section] - - def _nodes_for_sections(self, doc): - """Return list of doctree nodes for additional sections""" - nodelist = [] - for section in doc.sections: - if section.kind == QAPIDoc.Kind.TODO: - # Hide TODO: sections - continue - - if section.kind == QAPIDoc.Kind.PLAIN: - # Sphinx cannot handle sectionless titles; - # Instead, just append the results to the prior section. - container = nodes.container() - self._parse_text_into_node(section.text, container) - nodelist += container.children - continue - - snode = self._make_section(section.kind.name.title()) - self._parse_text_into_node(dedent(section.text), snode) - nodelist.append(snode) - return nodelist - - def _nodes_for_if_section(self, ifcond): - """Return list of doctree nodes for the "If" section""" - nodelist = [] - if ifcond.is_present(): - snode = self._make_section('If') - snode += nodes.paragraph( - '', '', *self._nodes_for_ifcond(ifcond, with_if=False) - ) - nodelist.append(snode) - return nodelist - - def _add_doc(self, typ, sections): - """Add documentation for a command/object/enum... - - We assume we're documenting the thing defined in self._cur_doc. - typ is the type of thing being added ("Command", "Object", etc) - - sections is a list of nodes for sections to add to the definition. - """ - - doc = self._cur_doc - snode = nodes.section(ids=[self._sphinx_directive.new_serialno()]) - snode += nodes.title('', '', *[nodes.literal(doc.symbol, doc.symbol), - nodes.Text(' (' + typ + ')')]) - self._parse_text_into_node(doc.body.text, snode) - for s in sections: - if s is not None: - snode += s - self._add_node_to_current_heading(snode) - - def visit_enum_type(self, name, info, ifcond, features, members, prefix): - doc = self._cur_doc - self._add_doc('Enum', - self._nodes_for_enum_values(doc) - + self._nodes_for_features(doc) - + self._nodes_for_sections(doc) - + self._nodes_for_if_section(ifcond)) - - def visit_object_type(self, name, info, ifcond, features, - base, members, branches): - doc = self._cur_doc - if base and base.is_implicit(): - base = None - self._add_doc('Object', - self._nodes_for_members(doc, 'Members', base, branches) - + self._nodes_for_features(doc) - + self._nodes_for_sections(doc) - + self._nodes_for_if_section(ifcond)) - - def visit_alternate_type(self, name, info, ifcond, features, - alternatives): - doc = self._cur_doc - self._add_doc('Alternate', - self._nodes_for_members(doc, 'Members') - + self._nodes_for_features(doc) - + self._nodes_for_sections(doc) - + self._nodes_for_if_section(ifcond)) - - def visit_command(self, name, info, ifcond, features, arg_type, - ret_type, gen, success_response, boxed, allow_oob, - allow_preconfig, coroutine): - doc = self._cur_doc - self._add_doc('Command', - self._nodes_for_arguments(doc, arg_type) - + self._nodes_for_features(doc) - + self._nodes_for_sections(doc) - + self._nodes_for_if_section(ifcond)) - - def visit_event(self, name, info, ifcond, features, arg_type, boxed): - doc = self._cur_doc - self._add_doc('Event', - self._nodes_for_arguments(doc, arg_type) - + self._nodes_for_features(doc) - + self._nodes_for_sections(doc) - + self._nodes_for_if_section(ifcond)) - - def symbol(self, doc, entity): - """Add documentation for one symbol to the document tree - - This is the main entry point which causes us to add documentation - nodes for a symbol (which could be a 'command', 'object', 'event', - etc). We do this by calling 'visit' on the schema entity, which - will then call back into one of our visit_* methods, depending - on what kind of thing this symbol is. - """ - self._cur_doc = doc - entity.visit(self) - self._cur_doc = None - - def _start_new_heading(self, heading, level): - """Start a new heading at the specified heading level - - Create a new section whose title is 'heading' and which is placed - in the docutils node tree as a child of the most recent level-1 - heading. Subsequent document sections (commands, freeform doc chunks, - etc) will be placed as children of this new heading section. - """ - if len(self._active_headings) < level: - raise QAPISemError(self._cur_doc.info, - 'Level %d subheading found outside a ' - 'level %d heading' - % (level, level - 1)) - snode = self._make_section(heading) - self._active_headings[level - 1] += snode - self._active_headings = self._active_headings[:level] - self._active_headings.append(snode) - return snode - - def _add_node_to_current_heading(self, node): - """Add the node to whatever the current active heading is""" - self._active_headings[-1] += node - - def freeform(self, doc): - """Add a piece of 'freeform' documentation to the document tree - - A 'freeform' document chunk doesn't relate to any particular - symbol (for instance, it could be an introduction). - - If the freeform document starts with a line of the form - '= Heading text', this is a section or subsection heading, with - the heading level indicated by the number of '=' signs. - """ - - # QAPIDoc documentation says free-form documentation blocks - # must have only a body section, nothing else. - assert not doc.sections - assert not doc.args - assert not doc.features - self._cur_doc = doc - - text = doc.body.text - if re.match(r'=+ ', text): - # Section/subsection heading (if present, will always be - # the first line of the block) - (heading, _, text) = text.partition('\n') - (leader, _, heading) = heading.partition(' ') - node = self._start_new_heading(heading, len(leader)) - if text == '': - return - else: - node = nodes.container() - - self._parse_text_into_node(text, node) - self._cur_doc = None - - def _parse_text_into_node(self, doctext, node): - """Parse a chunk of QAPI-doc-format text into the node - - The doc comment can contain most inline rST markup, including - bulleted and enumerated lists. - As an extra permitted piece of markup, @var will be turned - into ``var``. - """ - - # Handle the "@var means ``var`` case - doctext = re.sub(r'@([\w-]+)', r'``\1``', doctext) - - rstlist = ViewList() - for line in doctext.splitlines(): - # The reported line number will always be that of the start line - # of the doc comment, rather than the actual location of the error. - # Being more precise would require overhaul of the QAPIDoc class - # to track lines more exactly within all the sub-parts of the doc - # comment, as well as counting lines here. - rstlist.append(line, self._cur_doc.info.fname, - self._cur_doc.info.line) - # Append a blank line -- in some cases rST syntax errors get - # attributed to the line after one with actual text, and if there - # isn't anything in the ViewList corresponding to that then Sphinx - # 1.6's AutodocReporter will then misidentify the source/line location - # in the error message (usually attributing it to the top-level - # .rst file rather than the offending .json file). The extra blank - # line won't affect the rendered output. - rstlist.append("", self._cur_doc.info.fname, self._cur_doc.info.line) - self._sphinx_directive.do_parse(rstlist, node) - - def get_document_node(self): - """Return the root docutils node which makes up the document""" - return self._top_node diff --git a/python/tests/qapi-isort.sh b/python/tests/qapi-isort.sh index 78dd947f68..067c16d5d9 100755 --- a/python/tests/qapi-isort.sh +++ b/python/tests/qapi-isort.sh @@ -3,6 +3,6 @@ python3 -m isort --sp . -c ../scripts/qapi/ # Force isort to recognize "compat" as a local module and not third-party -python3 -m isort --sp . -c -p compat -p qapidoc_legacy \ +python3 -m isort --sp . -c -p compat \ ../docs/sphinx/qapi_domain.py \ ../docs/sphinx/qapidoc.py diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt index 17a1d56ef1..74b73681d3 100644 --- a/tests/qapi-schema/doc-good.txt +++ b/tests/qapi-schema/doc-good.txt @@ -1,6 +1,8 @@ Section ******* +Just text, no heading. + Subsection ========== @@ -35,249 +37,145 @@ Example: -> in <- out Examples: - *verbatim* - {braces} +Enum Enum + *Availability*: "IFCOND" -"Enum" (Enum) -------------- + Values: + * **one** -- The _one_ {and only}, description on the same line + * **two** -- Not documented -Values -~~~~~~ + Features: + * **enum-feat** -- Also _one_ {and only} -"one" (**If: **"IFONE") - The _one_ {and only}, description on the same line + * **enum-member-feat** -- a member feature -"two" - Not documented + "two" is undocumented +Object Base + *Availability*: "IFALL1 and IFALL2" -Features -~~~~~~~~ + Members: + * **base1** ("Enum") -- description starts on a new line, + minimally indented -"enum-feat" - Also _one_ {and only} +Object Variant1 -"enum-member-feat" - a member feature + A paragraph -"two" is undocumented + Another paragraph + "var1" is undocumented -If -~~ + Members: + * **var1** ("string") -- Not documented -"IFCOND" + Features: + * **variant1-feat** -- a feature + * **member-feat** -- a member feature -"Base" (Object) ---------------- +Object Variant2 +Object Object -Members -~~~~~~~ + Members: + * The members of "Base". -"base1": "Enum" - description starts on a new line, minimally indented + * When "base1" is "one": The members of "Variant1". + * When "base1" is "two": The members of "Variant2". -If -~~ + Features: + * **union-feat1** -- a feature -"IFALL1 and IFALL2" +Alternate Alternate + *Availability*: "not (IFONE or IFTWO)" + Alternatives: + * **i** ("int") -- description starts on the same line remainder + indented the same "b" is undocumented -"Variant1" (Object) -------------------- + * **b** ("boolean") -- Not documented -A paragraph - -Another paragraph - -"var1" is undocumented - - -Members -~~~~~~~ - -"var1": "string" (**If: **"IFSTR") - Not documented - - -Features -~~~~~~~~ - -"variant1-feat" - a feature - -"member-feat" - a member feature - - -"Variant2" (Object) -------------------- - - -"Object" (Object) ------------------ - - -Members -~~~~~~~ - -The members of "Base" -The members of "Variant1" when "base1" is ""one"" -The members of "Variant2" when "base1" is ""two"" (**If: **"IFONE or -IFTWO") - -Features -~~~~~~~~ - -"union-feat1" - a feature - - -"Alternate" (Alternate) ------------------------ - - -Members -~~~~~~~ - -"i": "int" - description starts on the same line remainder indented the same "b" - is undocumented - -"b": "boolean" - Not documented - - -Features -~~~~~~~~ - -"alt-feat" - a feature - - -If -~~ - -"not (IFONE or IFTWO)" + Features: + * **alt-feat** -- a feature Another subsection ================== +Command cmd (Since: 2.10) -"cmd" (Command) ---------------- + Arguments: + * **arg1** ("int") -- description starts on a new line, indented + * **arg2** ("string", *optional*) -- description starts on the + same line remainder indented differently -Arguments -~~~~~~~~~ + * **arg3** ("boolean") -- Not documented -"arg1": "int" - description starts on a new line, indented + Features: + * **cmd-feat1** -- a feature -"arg2": "string" (optional) - description starts on the same line remainder indented differently + * **cmd-feat2** -- another feature -"arg3": "boolean" - Not documented + Note: + "arg3" is undocumented -Features -~~~~~~~~ + Return: + "Object" -- "Object" -"cmd-feat1" - a feature + Errors: + some -"cmd-feat2" - another feature + Notes: -Note: + * Lorem ipsum dolor sit amet - "arg3" is undocumented + * Ut enim ad minim veniam + Duis aute irure dolor -Returns -~~~~~~~ + Example: Ideal fast-food burger situation: -"Object" + -> "in" + <- "out" + Examples: -Errors -~~~~~~ + - Not a QMP code block + - Merely a preformatted code block literal + It isn't even an rST list. + - *verbatim* + - {braces} -some + Note:: + Ceci n'est pas une note -Notes: +Command cmd-boxed -* Lorem ipsum dolor sit amet + If you're bored enough to read this, go see a video of boxed cats -* Ut enim ad minim veniam + Arguments: + * The members of "Object". -Duis aute irure dolor + Features: + * **cmd-feat1** -- a feature -Example: Ideal fast-food burger situation: + * **cmd-feat2** -- another feature - -> "in" - <- "out" + Example:: -Examples: + -> "this example" - - Not a QMP code block - - Merely a preformatted code block literal - It isn't even an rST list. - - *verbatim* - - {braces} + <- ... has no title ... -Note:: - Ceci n'est pas une note +Event EVT_BOXED + Members: + * The members of "Object". -Since -~~~~~ - -2.10 - - -"cmd-boxed" (Command) ---------------------- - -If you're bored enough to read this, go see a video of boxed cats - - -Arguments -~~~~~~~~~ - -The members of "Object" - -Features -~~~~~~~~ - -"cmd-feat1" - a feature - -"cmd-feat2" - another feature - -Example:: - - -> "this example" - - <- ... has no title ... - - -"EVT_BOXED" (Event) -------------------- - - -Arguments -~~~~~~~~~ - -The members of "Object" - -Features -~~~~~~~~ - -"feat3" - a feature + Features: + * **feat3** -- a feature From 6c10778826a873b9012d95e63298a6f879debcaa Mon Sep 17 00:00:00 2001 From: John Snow Date: Wed, 18 Jun 2025 12:53:52 -0400 Subject: [PATCH 04/29] docs/sphinx: remove special parsing for freeform sections Remove the QAPI doc section heading syntax, use plain rST section headings instead. Tests and documentation are updated to match. Interestingly, Plain rST headings work fine before this patch, except for over- and underlining with '=', which the doc parser rejected as invalid QAPI doc section heading in free-form comments. Signed-off-by: John Snow Message-ID: <20250618165353.1980365-5-jsnow@redhat.com> Reviewed-by: Markus Armbruster [Add more detail to commit message] Signed-off-by: Markus Armbruster --- docs/devel/qapi-code-gen.rst | 28 ++++++++++++++------- docs/interop/firmware.json | 4 ++- docs/interop/vhost-user.json | 4 ++- docs/sphinx/qapidoc.py | 37 +--------------------------- qapi/acpi.json | 4 ++- qapi/audio.json | 4 ++- qapi/authz.json | 4 ++- qapi/block-core.json | 3 ++- qapi/block-export.json | 3 ++- qapi/block.json | 7 ++++-- qapi/char.json | 4 ++- qapi/common.json | 4 ++- qapi/compat.json | 4 ++- qapi/control.json | 4 ++- qapi/crypto.json | 4 ++- qapi/cryptodev.json | 4 ++- qapi/cxl.json | 4 ++- qapi/dump.json | 4 ++- qapi/ebpf.json | 4 ++- qapi/error.json | 4 ++- qapi/introspect.json | 4 ++- qapi/job.json | 4 ++- qapi/machine-common.json | 4 ++- qapi/machine.json | 4 ++- qapi/migration.json | 4 ++- qapi/misc.json | 4 ++- qapi/net.json | 4 ++- qapi/pci.json | 4 ++- qapi/qapi-schema.json | 4 ++- qapi/qdev.json | 4 ++- qapi/qom.json | 4 ++- qapi/replay.json | 4 ++- qapi/rocker.json | 4 ++- qapi/run-state.json | 4 ++- qapi/sockets.json | 4 ++- qapi/stats.json | 4 ++- qapi/tpm.json | 4 ++- qapi/trace.json | 4 ++- qapi/transaction.json | 4 ++- qapi/uefi.json | 4 ++- qapi/ui.json | 14 ++++++++--- qapi/vfio.json | 4 ++- qapi/virtio.json | 4 ++- qapi/yank.json | 4 ++- scripts/qapi/parser.py | 7 ------ storage-daemon/qapi/qapi-schema.json | 8 ++++-- tests/qapi-schema/doc-good.json | 10 +++++--- tests/qapi-schema/doc-good.out | 10 +++++--- 48 files changed, 173 insertions(+), 106 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 231cc0fecf..dfdbeac5a5 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -876,25 +876,35 @@ structuring content. Headings and subheadings ~~~~~~~~~~~~~~~~~~~~~~~~ -A free-form documentation comment containing a line which starts with -some ``=`` symbols and then a space defines a section heading:: +Free-form documentation does not start with ``@SYMBOL`` and can contain +arbitrary rST markup. Headings can be marked up using the standard rST +syntax:: ## - # = This is a top level heading + # ************************* + # This is a level 2 heading + # ************************* # # This is a free-form comment which will go under the # top level heading. ## ## - # == This is a second level heading + # This is a third level heading + # ============================== + # + # Level 4 + # _______ + # + # Level 5 + # ^^^^^^^ + # + # Level 6 + # """"""" ## -A heading line must be the first line of the documentation -comment block. - -Section headings must always be correctly nested, so you can only -define a third-level heading inside a second-level heading, and so on. +Level 1 headings are reserved for use by the generated documentation +page itself, leaving level 2 as the highest level that should be used. Documentation markup diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json index 745d21d822..f46fdedfa8 100644 --- a/docs/interop/firmware.json +++ b/docs/interop/firmware.json @@ -11,7 +11,9 @@ # later. See the COPYING file in the top-level directory. ## -# = Firmware +# ******** +# Firmware +# ******** ## { 'pragma': { diff --git a/docs/interop/vhost-user.json b/docs/interop/vhost-user.json index b6ade9e493..095eb99cf7 100644 --- a/docs/interop/vhost-user.json +++ b/docs/interop/vhost-user.json @@ -10,7 +10,9 @@ # later. See the COPYING file in the top-level directory. ## -# = vhost user backend discovery & capabilities +# ******************************************* +# vhost user backend discovery & capabilities +# ******************************************* ## ## diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index d5d2b5eeb5..b794cde697 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -399,44 +399,9 @@ def visit_module(self, path: str) -> None: self.ensure_blank_line() def visit_freeform(self, doc: QAPIDoc) -> None: - # TODO: Once the old qapidoc transformer is deprecated, freeform - # sections can be updated to pure rST, and this transformed removed. - # - # For now, translate our micro-format into rST. Code adapted - # from Peter Maydell's freeform(). - assert len(doc.all_sections) == 1, doc.all_sections body = doc.all_sections[0] - text = self.reformat_arobase(body.text) - info = doc.info - - if re.match(r"=+ ", text): - # Section/subsection heading (if present, will always be the - # first line of the block) - (heading, _, text) = text.partition("\n") - (leader, _, heading) = heading.partition(" ") - # Implicit +1 for heading in the containing .rst doc - level = len(leader) + 1 - - # https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections - markers = ' #*=_^"' - overline = level <= 2 - marker = markers[level] - - self.ensure_blank_line() - # This credits all 2 or 3 lines to the single source line. - if overline: - self.add_line(marker * len(heading), info) - self.add_line(heading, info) - self.add_line(marker * len(heading), info) - self.ensure_blank_line() - - # Eat blank line(s) and advance info - trimmed = text.lstrip("\n") - text = trimmed - info = info.next_line(len(text) - len(trimmed) + 1) - - self.add_lines(text, info) + self.add_lines(self.reformat_arobase(body.text), doc.info) self.ensure_blank_line() def visit_entity(self, ent: QAPISchemaDefinition) -> None: diff --git a/qapi/acpi.json b/qapi/acpi.json index 2d53b82365..90f8f564fd 100644 --- a/qapi/acpi.json +++ b/qapi/acpi.json @@ -6,7 +6,9 @@ # SPDX-License-Identifier: GPL-2.0-or-later ## -# = ACPI +# **** +# ACPI +# **** ## ## diff --git a/qapi/audio.json b/qapi/audio.json index 16de231f6d..6a22ca384a 100644 --- a/qapi/audio.json +++ b/qapi/audio.json @@ -7,7 +7,9 @@ # See the COPYING file in the top-level directory. ## -# = Audio +# ***** +# Audio +# ***** ## ## diff --git a/qapi/authz.json b/qapi/authz.json index 7fc6e3032e..ad1b4b3af0 100644 --- a/qapi/authz.json +++ b/qapi/authz.json @@ -2,7 +2,9 @@ # vim: filetype=python ## -# = User authorization +# ****************** +# User authorization +# ****************** ## ## diff --git a/qapi/block-core.json b/qapi/block-core.json index 1df6644f0d..8b413946ff 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -2,7 +2,8 @@ # vim: filetype=python ## -# == Block core (VM unrelated) +# Block core (VM unrelated) +# ========================= ## { 'include': 'common.json' } diff --git a/qapi/block-export.json b/qapi/block-export.json index ed4deb54db..2241bfecf2 100644 --- a/qapi/block-export.json +++ b/qapi/block-export.json @@ -2,7 +2,8 @@ # vim: filetype=python ## -# == Block device exports +# Block device exports +# ==================== ## { 'include': 'sockets.json' } diff --git a/qapi/block.json b/qapi/block.json index 1490a1a17f..2d54a81c36 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -2,13 +2,16 @@ # vim: filetype=python ## -# = Block devices +# ************* +# Block devices +# ************* ## { 'include': 'block-core.json' } ## -# == Additional block stuff (VM related) +# Additional block stuff (VM related) +# =================================== ## ## diff --git a/qapi/char.json b/qapi/char.json index df6e325e2e..f38d04986d 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -3,7 +3,9 @@ # ## -# = Character devices +# ***************** +# Character devices +# ***************** ## { 'include': 'sockets.json' } diff --git a/qapi/common.json b/qapi/common.json index 0e3a0bbbfb..af7e3d618a 100644 --- a/qapi/common.json +++ b/qapi/common.json @@ -2,7 +2,9 @@ # vim: filetype=python ## -# = Common data types +# ***************** +# Common data types +# ***************** ## ## diff --git a/qapi/compat.json b/qapi/compat.json index 42034d9368..90b8d51cf2 100644 --- a/qapi/compat.json +++ b/qapi/compat.json @@ -2,7 +2,9 @@ # vim: filetype=python ## -# = Compatibility policy +# ******************** +# Compatibility policy +# ******************** ## ## diff --git a/qapi/control.json b/qapi/control.json index 34b733f63b..ab0b3a3bbe 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -3,7 +3,9 @@ # ## -# = QMP monitor control +# ******************* +# QMP monitor control +# ******************* ## ## diff --git a/qapi/crypto.json b/qapi/crypto.json index 9ec6301e18..21006de36c 100644 --- a/qapi/crypto.json +++ b/qapi/crypto.json @@ -3,7 +3,9 @@ # ## -# = Cryptography +# ************ +# Cryptography +# ************ ## ## diff --git a/qapi/cryptodev.json b/qapi/cryptodev.json index b13db26403..1f49e1822c 100644 --- a/qapi/cryptodev.json +++ b/qapi/cryptodev.json @@ -5,7 +5,9 @@ # See the COPYING file in the top-level directory. ## -# = Cryptography devices +# ******************** +# Cryptography devices +# ******************** ## ## diff --git a/qapi/cxl.json b/qapi/cxl.json index 8f2e9237b1..52cc5d4f33 100644 --- a/qapi/cxl.json +++ b/qapi/cxl.json @@ -2,7 +2,9 @@ # vim: filetype=python ## -# = CXL devices +# *********** +# CXL devices +# *********** ## ## diff --git a/qapi/dump.json b/qapi/dump.json index d0ba1f0596..0642ca157b 100644 --- a/qapi/dump.json +++ b/qapi/dump.json @@ -5,7 +5,9 @@ # See the COPYING file in the top-level directory. ## -# = Dump guest memory +# ***************** +# Dump guest memory +# ***************** ## ## diff --git a/qapi/ebpf.json b/qapi/ebpf.json index db19ae850f..d45054e666 100644 --- a/qapi/ebpf.json +++ b/qapi/ebpf.json @@ -5,7 +5,9 @@ # See the COPYING file in the top-level directory. ## -# = eBPF Objects +# ************ +# eBPF Objects +# ************ # # eBPF object is an ELF binary that contains the eBPF program and eBPF # map description(BTF). Overall, eBPF object should contain the diff --git a/qapi/error.json b/qapi/error.json index 135c1e8231..54cb02fb88 100644 --- a/qapi/error.json +++ b/qapi/error.json @@ -2,7 +2,9 @@ # vim: filetype=python ## -# = QMP errors +# ********** +# QMP errors +# ********** ## ## diff --git a/qapi/introspect.json b/qapi/introspect.json index e9e0297282..26d8839f19 100644 --- a/qapi/introspect.json +++ b/qapi/introspect.json @@ -10,7 +10,9 @@ # See the COPYING file in the top-level directory. ## -# = QMP introspection +# ***************** +# QMP introspection +# ***************** ## ## diff --git a/qapi/job.json b/qapi/job.json index 126fa5ce60..16b280f52f 100644 --- a/qapi/job.json +++ b/qapi/job.json @@ -2,7 +2,9 @@ # vim: filetype=python ## -# = Background jobs +# *************** +# Background jobs +# *************** ## ## diff --git a/qapi/machine-common.json b/qapi/machine-common.json index 298e51f373..0f01599130 100644 --- a/qapi/machine-common.json +++ b/qapi/machine-common.json @@ -5,7 +5,9 @@ # See the COPYING file in the top-level directory. ## -# = Common machine types +# ******************** +# Common machine types +# ******************** ## ## diff --git a/qapi/machine.json b/qapi/machine.json index f712e7da6d..af00a20b1f 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -5,7 +5,9 @@ # See the COPYING file in the top-level directory. ## -# = Machines +# ******** +# Machines +# ******** ## { 'include': 'common.json' } diff --git a/qapi/migration.json b/qapi/migration.json index 2d39a8f748..3bf97df5d8 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -3,7 +3,9 @@ # ## -# = Migration +# ********* +# Migration +# ********* ## { 'include': 'common.json' } diff --git a/qapi/misc.json b/qapi/misc.json index 4b9e601cfa..a180c16db2 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -3,7 +3,9 @@ # ## -# = Miscellanea +# *********** +# Miscellanea +# *********** ## { 'include': 'common.json' } diff --git a/qapi/net.json b/qapi/net.json index 97ea183981..3b03843c16 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -3,7 +3,9 @@ # ## -# = Net devices +# *********** +# Net devices +# *********** ## { 'include': 'sockets.json' } diff --git a/qapi/pci.json b/qapi/pci.json index dc85a41d28..a8671cd9ac 100644 --- a/qapi/pci.json +++ b/qapi/pci.json @@ -6,7 +6,9 @@ # SPDX-License-Identifier: GPL-2.0-or-later ## -# = PCI +# *** +# PCI +# *** ## ## diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index a8f66163cb..49b9a0267d 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -1,7 +1,9 @@ # -*- Mode: Python -*- # vim: filetype=python ## -# = Introduction +# ************ +# Introduction +# ************ # # This manual describes the commands and events supported by the QEMU # Monitor Protocol (QMP). diff --git a/qapi/qdev.json b/qapi/qdev.json index 32c7d10046..441ed518b8 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -5,7 +5,9 @@ # See the COPYING file in the top-level directory. ## -# = Device infrastructure (qdev) +# **************************** +# Device infrastructure (qdev) +# **************************** ## { 'include': 'qom.json' } diff --git a/qapi/qom.json b/qapi/qom.json index b133b06447..f68f72fbbc 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -10,7 +10,9 @@ { 'include': 'crypto.json' } ## -# = QEMU Object Model (QOM) +# *********************** +# QEMU Object Model (QOM) +# *********************** ## ## diff --git a/qapi/replay.json b/qapi/replay.json index 35e0c4a692..e46c5c1d3f 100644 --- a/qapi/replay.json +++ b/qapi/replay.json @@ -3,7 +3,9 @@ # ## -# = Record/replay +# ************* +# Record/replay +# ************* ## { 'include': 'common.json' } diff --git a/qapi/rocker.json b/qapi/rocker.json index 0c7ef1f77c..e494964952 100644 --- a/qapi/rocker.json +++ b/qapi/rocker.json @@ -2,7 +2,9 @@ # vim: filetype=python ## -# = Rocker switch device +# ******************** +# Rocker switch device +# ******************** ## ## diff --git a/qapi/run-state.json b/qapi/run-state.json index fd09beb35c..083a3c5eb3 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -3,7 +3,9 @@ # ## -# = VM run state +# ************ +# VM run state +# ************ ## ## diff --git a/qapi/sockets.json b/qapi/sockets.json index f9f559daba..b5f4a8fecd 100644 --- a/qapi/sockets.json +++ b/qapi/sockets.json @@ -2,7 +2,9 @@ # vim: filetype=python ## -# = Socket data types +# ***************** +# Socket data types +# ***************** ## ## diff --git a/qapi/stats.json b/qapi/stats.json index 8902ef94e0..78b88881ea 100644 --- a/qapi/stats.json +++ b/qapi/stats.json @@ -9,7 +9,9 @@ # SPDX-License-Identifier: GPL-2.0-or-later ## -# = Statistics +# ********** +# Statistics +# ********** ## ## diff --git a/qapi/tpm.json b/qapi/tpm.json index a16a72edb9..e66b107f1d 100644 --- a/qapi/tpm.json +++ b/qapi/tpm.json @@ -3,7 +3,9 @@ # ## -# = TPM (trusted platform module) devices +# ************************************* +# TPM (trusted platform module) devices +# ************************************* ## ## diff --git a/qapi/trace.json b/qapi/trace.json index eb5f63f513..d08c9c6a88 100644 --- a/qapi/trace.json +++ b/qapi/trace.json @@ -7,7 +7,9 @@ # See the COPYING file in the top-level directory. ## -# = Tracing +# ******* +# Tracing +# ******* ## ## diff --git a/qapi/transaction.json b/qapi/transaction.json index 9d9e7af26c..927035f5a7 100644 --- a/qapi/transaction.json +++ b/qapi/transaction.json @@ -3,7 +3,9 @@ # ## -# = Transactions +# ************ +# Transactions +# ************ ## { 'include': 'block-core.json' } diff --git a/qapi/uefi.json b/qapi/uefi.json index 6592183d6c..a206c2e953 100644 --- a/qapi/uefi.json +++ b/qapi/uefi.json @@ -3,7 +3,9 @@ # ## -# = UEFI Variable Store +# ******************* +# UEFI Variable Store +# ******************* # # The QEMU efi variable store implementation (hw/uefi/) uses this to # store non-volatile variables in json format on disk. diff --git a/qapi/ui.json b/qapi/ui.json index 514fa159b1..f5e77ae19d 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -3,7 +3,9 @@ # ## -# = Remote desktop +# ************** +# Remote desktop +# ************** ## { 'include': 'common.json' } @@ -200,7 +202,8 @@ 'if': 'CONFIG_PIXMAN' } ## -# == Spice +# Spice +# ===== ## ## @@ -461,7 +464,8 @@ 'if': 'CONFIG_SPICE' } ## -# == VNC +# VNC +# === ## ## @@ -794,7 +798,9 @@ 'if': 'CONFIG_VNC' } ## -# = Input +# ***** +# Input +# ***** ## ## diff --git a/qapi/vfio.json b/qapi/vfio.json index b53b7caecd..a1a9c5b673 100644 --- a/qapi/vfio.json +++ b/qapi/vfio.json @@ -3,7 +3,9 @@ # ## -# = VFIO devices +# ************ +# VFIO devices +# ************ ## ## diff --git a/qapi/virtio.json b/qapi/virtio.json index 73df718a26..3cac0774f7 100644 --- a/qapi/virtio.json +++ b/qapi/virtio.json @@ -3,7 +3,9 @@ # ## -# = Virtio devices +# ************** +# Virtio devices +# ************** ## ## diff --git a/qapi/yank.json b/qapi/yank.json index 30f46c97c9..d13a8e9117 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -3,7 +3,9 @@ # ## -# = Yank feature +# ************ +# Yank feature +# ************ ## ## diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 949d9e8bff..aad7e249f8 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -597,22 +597,15 @@ def get_doc(self) -> 'QAPIDoc': # Free-form documentation doc = QAPIDoc(info) doc.ensure_untagged_section(self.info) - first = True while line is not None: if match := self._match_at_name_colon(line): raise QAPIParseError( self, "'@%s:' not allowed in free-form documentation" % match.group(1)) - if line.startswith('='): - if not first: - raise QAPIParseError( - self, - "'=' heading must come first in a comment block") doc.append_line(line) self.accept(False) line = self.get_doc_line() - first = False self.accept() doc.end() diff --git a/storage-daemon/qapi/qapi-schema.json b/storage-daemon/qapi/qapi-schema.json index 0427594c98..478e7a92b2 100644 --- a/storage-daemon/qapi/qapi-schema.json +++ b/storage-daemon/qapi/qapi-schema.json @@ -14,7 +14,9 @@ # storage daemon. ## -# = Introduction +# ************ +# Introduction +# ************ # # This manual describes the commands and events supported by the QEMU # storage daemon QMP. @@ -51,7 +53,9 @@ { 'include': '../../qapi/job.json' } ## -# = Block devices +# ************* +# Block devices +# ************* ## { 'include': '../../qapi/block-core.json' } { 'include': '../../qapi/block-export.json' } diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json index 14b808f909..fac13425b7 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -8,7 +8,9 @@ 'documentation-exceptions': [ 'Enum', 'Variant1', 'Alternate', 'cmd' ] } } ## -# = Section +# ******* +# Section +# ******* ## ## @@ -16,7 +18,8 @@ ## ## -# == Subsection +# Subsection +# ========== # # *with emphasis* # @var {in braces} @@ -144,7 +147,8 @@ 'if': { 'not': { 'any': [ 'IFONE', 'IFTWO' ] } } } ## -# == Another subsection +# Another subsection +# ================== ## ## diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index dc8352eed4..04a5507264 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -55,13 +55,16 @@ event EVT_BOXED Object feature feat3 doc freeform body= -= Section +******* +Section +******* doc freeform body= Just text, no heading. doc freeform body= -== Subsection +Subsection +========== *with emphasis* @var {in braces} @@ -155,7 +158,8 @@ description starts on the same line a feature doc freeform body= -== Another subsection +Another subsection +================== doc symbol=cmd body= From 62c4dc4b69ef7dcfcc476913a9c5fc15329e0290 Mon Sep 17 00:00:00 2001 From: John Snow Date: Wed, 18 Jun 2025 12:53:53 -0400 Subject: [PATCH 05/29] qapi: lift restriction on using '=' in doc blocks We reject lines starting with '=' in definition documentation. This made sense when such lines were headings in free-form documentation, but not in definition documentation. Before the previous commit, lines starting with '=' were headings in free-form documentation, and rejected in definition documentation, where such headings could not work. The previous commit dropped the headings feature from free-form documentation, because we can simply use plain rST headings. Rejecting them in definition documentation no longer makes sense, so drop that, too. Signed-off-by: John Snow Message-ID: <20250618165353.1980365-6-jsnow@redhat.com> Reviewed-by: Markus Armbruster [Amend commit message to explain why] Signed-off-by: Markus Armbruster --- scripts/qapi/parser.py | 4 ---- tests/qapi-schema/doc-bad-section.err | 1 - tests/qapi-schema/doc-bad-section.json | 10 ---------- tests/qapi-schema/doc-bad-section.out | 0 tests/qapi-schema/meson.build | 1 - 5 files changed, 16 deletions(-) delete mode 100644 tests/qapi-schema/doc-bad-section.err delete mode 100644 tests/qapi-schema/doc-bad-section.json delete mode 100644 tests/qapi-schema/doc-bad-section.out diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index aad7e249f8..d43a123cd7 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -584,10 +584,6 @@ def get_doc(self) -> 'QAPIDoc': doc.append_line(text) line = self.get_doc_indented(doc) no_more_args = True - elif line.startswith('='): - raise QAPIParseError( - self, - "unexpected '=' markup in definition documentation") else: # plain paragraph doc.ensure_untagged_section(self.info) diff --git a/tests/qapi-schema/doc-bad-section.err b/tests/qapi-schema/doc-bad-section.err deleted file mode 100644 index 785cacc08c..0000000000 --- a/tests/qapi-schema/doc-bad-section.err +++ /dev/null @@ -1 +0,0 @@ -doc-bad-section.json:5:1: unexpected '=' markup in definition documentation diff --git a/tests/qapi-schema/doc-bad-section.json b/tests/qapi-schema/doc-bad-section.json deleted file mode 100644 index 8175d95867..0000000000 --- a/tests/qapi-schema/doc-bad-section.json +++ /dev/null @@ -1,10 +0,0 @@ -# = section within an expression comment - -## -# @Enum: -# == No good here -# @one: The _one_ {and only} -# -# @two is undocumented -## -{ 'enum': 'Enum', 'data': [ 'one', 'two' ] } diff --git a/tests/qapi-schema/doc-bad-section.out b/tests/qapi-schema/doc-bad-section.out deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/tests/qapi-schema/meson.build b/tests/qapi-schema/meson.build index 9577178b6f..c47025d16d 100644 --- a/tests/qapi-schema/meson.build +++ b/tests/qapi-schema/meson.build @@ -61,7 +61,6 @@ schemas = [ 'doc-bad-event-arg.json', 'doc-bad-feature.json', 'doc-bad-indent.json', - 'doc-bad-section.json', 'doc-bad-symbol.json', 'doc-bad-union-member.json', 'doc-before-include.json', From c13ceeb42df5452690fc530269696f59da921b31 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Tue, 8 Jul 2025 09:28:27 +0200 Subject: [PATCH 06/29] qapi: Clean up "This command will do ..." command descriptions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use imperative mood "Do ..." instead. Signed-off-by: Markus Armbruster Message-ID: <20250708072828.105185-2-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- qapi/control.json | 9 +++++---- qapi/misc-i386.json | 11 +++++------ qapi/qom.json | 10 ++++------ 3 files changed, 14 insertions(+), 16 deletions(-) diff --git a/qapi/control.json b/qapi/control.json index ab0b3a3bbe..5fed0701f8 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -160,10 +160,11 @@ ## # @quit: # -# This command will cause the QEMU process to exit gracefully. 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. +# Request graceful QEMU process termination. +# +# 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 # diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json index 5fefa0a484..b53ed39288 100644 --- a/qapi/misc-i386.json +++ b/qapi/misc-i386.json @@ -6,9 +6,9 @@ ## # @rtc-reset-reinjection: # -# This command will reset the RTC interrupt reinjection backlog. Can -# be used if another mechanism to synchronize guest time is in effect, -# for example QEMU guest agent's guest-set-time command. +# Reset the RTC interrupt reinjection backlog. Can be used if another +# mechanism to synchronize guest time is in effect, for example QEMU +# guest agent's guest-set-time command. # # Use of this command is only applicable for x86 machines with an RTC, # and on other machines will silently return without performing any @@ -233,8 +233,7 @@ ## # @sev-inject-launch-secret: # -# This command injects a secret blob into memory of a SEV/SEV-ES -# guest. +# Inject a secret blob into a SEV/SEV-ES guest's memory. # # This is only valid on x86 machines configured with KVM and the # 'sev-guest' confidential virtualization object. SEV-SNP guests do @@ -272,7 +271,7 @@ ## # @query-sev-attestation-report: # -# This command is used to get the SEV attestation report. +# Get the SEV attestation report. # # This is only valid on x86 machines configured with KVM and the # 'sev-guest' confidential virtualization object. The attestation diff --git a/qapi/qom.json b/qapi/qom.json index f68f72fbbc..6c38e865a6 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -50,8 +50,7 @@ ## # @qom-list: # -# This command will list any properties of a object given a path in -# the object model. +# List properties of a object given a path in the object model. # # @path: the path within the object model. See @qom-get for a # description of this parameter. @@ -78,8 +77,7 @@ ## # @qom-get: # -# This command will get a property from a object model path and return -# the value. +# Get a property value. # # @path: The path within the object model. There are two forms of # supported paths--absolute and partial paths. @@ -130,7 +128,7 @@ ## # @qom-set: # -# This command will set a property from a object model path. +# Set a property value. # # @path: see @qom-get for a description of this parameter # @@ -173,7 +171,7 @@ ## # @qom-list-types: # -# This command will return a list of types given search parameters +# Return a list of types given search parameters. # # @implements: if specified, only return types that implement this # type name From 92227370eb3d844528e6d7bc2fb42525d8245eaf Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Tue, 8 Jul 2025 09:28:28 +0200 Subject: [PATCH 07/29] qapi: Clean up a few Errors: sections MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Use the conventional "- If " phrasing, optionally with ", ". Signed-off-by: Markus Armbruster Message-ID: <20250708072828.105185-3-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé --- qapi/misc-i386.json | 7 +++---- qapi/qom.json | 4 ++-- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json index b53ed39288..24a2e143f6 100644 --- a/qapi/misc-i386.json +++ b/qapi/misc-i386.json @@ -283,10 +283,9 @@ # Returns: SevAttestationReport objects. # # Errors: -# - This will return an error if the attestation report is -# unavailable, either due to an invalid guest configuration -# or if the guest has not reached the required SEV state, -# GenericError +# - If the attestation report is unavailable, either due to an +# invalid guest configuration or because the guest has not +# reached the required SEV state, GenericError # # Since: 6.1 # diff --git a/qapi/qom.json b/qapi/qom.json index 6c38e865a6..fbf94b9e09 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -1261,7 +1261,7 @@ # Create a QOM object. # # Errors: -# - Error if @qom-type is not a valid class name +# - If @qom-type is not a valid class name # # Since: 2.0 # @@ -1283,7 +1283,7 @@ # @id: the name of the QOM object to remove # # Errors: -# - Error if @id is not a valid id for a QOM object +# - If @id is not a valid id for a QOM object # # Since: 2.0 # From 2e51072ae5c0275733be748fbee3ce59df6d6261 Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:10:42 -0400 Subject: [PATCH 08/29] docs/qapi-domain: add return-nodesc This form is used to annotate a return type without an accompanying description, for when there is no "Returns:" information in the source doc, but we have a return type we want to generate a cross-reference to. The syntax is: :return-nodesc: TypeName It's primarily necessary because Sphinx always expects both a type and a description for the prior form and will format it accordingly. To have a reasonable rendering when the body is missing, we need to use a different info field list entirely. Signed-off-by: John Snow Message-ID: <20250711051045.51110-2-jsnow@redhat.com> Acked-by: Markus Armbruster [Long line wrapped] Signed-off-by: Markus Armbruster --- docs/devel/qapi-domain.rst | 31 +++++++++++++++++++++++++++++++ docs/sphinx/qapi_domain.py | 8 ++++++++ 2 files changed, 39 insertions(+) diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst index 11238723c2..b71890f660 100644 --- a/docs/devel/qapi-domain.rst +++ b/docs/devel/qapi-domain.rst @@ -242,6 +242,37 @@ Example:: } +``:return-nodesc:`` +------------------- + +Document the return type of a QAPI command, without an accompanying +description. + +:availability: This field list is only available in the body of the + Command directive. +:syntax: ``:return-nodesc: type`` +:type: `sphinx.util.docfields.Field + `_ + + +Example:: + + .. qapi:command:: query-replay + :since: 5.2 + + Retrieve the record/replay information. It includes current + instruction count which may be used for ``replay-break`` and + ``replay-seek`` commands. + + :return-nodesc: ReplayInfo + + .. qmp-example:: + + -> { "execute": "query-replay" } + <- { "return": { + "mode": "play", "filename": "log.rr", "icount": 220414 } + } + ``:value:`` ----------- diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index ebc46a72c6..f561dc465f 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -532,6 +532,14 @@ class QAPICommand(QAPIObject): names=("return",), can_collapse=True, ), + # :return-nodesc: TypeName + CompatField( + "returnvalue", + label=_("Return"), + names=("return-nodesc",), + bodyrolename="type", + has_arg=False, + ), ] ) From 636c96cd77d39aaec3e1c09b9990b76b015566e1 Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:10:43 -0400 Subject: [PATCH 09/29] qapi: Fix undocumented return values by generating something MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Generated command documentation lacks information on return value in several cases, e.g. query-tpm. The obvious fix would be to require a Returns: section when a command returns something. However, note that many existing Returns: sections are pretty useless: the description is basically the return type, which then gets rendered like "Return: – ". This suggests that a description is often not really necessary, and requiring one isn't useful. Instead, generate the obvious minimal thing when Returns: is absent: "Return: ". This auto-generated Return documentation is placed is as follows: 1. If we have arguments, return goes right after them. 2. Else if we have errors, return goes right before them. 3. Else if we have features, return goes right before them. 4. Else return goes right after the intro To facilitate this algorithm, a "TODO:" hack line is used to separate the intro from the remainder of the documentation block in cases where there are no other sections to separate the intro from e.g. examples and additional detail meant to appear below the key sections of interest. Signed-off-by: John Snow Message-ID: <20250711051045.51110-3-jsnow@redhat.com> Reviewed-by: Markus Armbruster [_insert_near_kind() code replaced by something simpler, commit message amended to explain why we're doing this] Signed-off-by: Markus Armbruster --- docs/sphinx/qapidoc.py | 14 ++++++++------ qapi/machine.json | 2 ++ scripts/qapi/parser.py | 37 +++++++++++++++++++++++++++++++++++++ scripts/qapi/schema.py | 3 +++ 4 files changed, 50 insertions(+), 6 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index b794cde697..c2f09bac16 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -258,16 +258,18 @@ def visit_feature(self, section: QAPIDoc.ArgSection) -> None: def visit_returns(self, section: QAPIDoc.Section) -> None: assert isinstance(self.entity, QAPISchemaCommand) rtype = self.entity.ret_type - # q_empty can produce None, but we won't be documenting anything - # without an explicit return statement in the doc block, and we - # should not have any such explicit statements when there is no - # return value. + # return statements will not be present (and won't be + # autogenerated) for any command that doesn't return + # *something*, so rtype will always be defined here. assert rtype typ = self.format_type(rtype) assert typ - assert section.text - self.add_field("return", typ, section.text, section.info) + + if section.text: + self.add_field("return", typ, section.text, section.info) + else: + self.add_lines(f":return-nodesc: {typ}", section.info) def visit_errors(self, section: QAPIDoc.Section) -> None: # If the section text does not start with a space, it means text diff --git a/qapi/machine.json b/qapi/machine.json index af00a20b1f..2d6a137f21 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -1303,6 +1303,8 @@ # 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 +# # .. qmp-example:: # # -> { "execute": "query-memory-size-summary" } diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index d43a123cd7..2529edf81a 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -804,6 +804,43 @@ def connect_feature(self, feature: 'QAPISchemaFeature') -> None: % feature.name) self.features[feature.name].connect(feature) + def ensure_returns(self, info: QAPISourceInfo) -> None: + + def _insert_near_kind( + kind: QAPIDoc.Kind, + new_sect: QAPIDoc.Section, + after: bool = False, + ) -> bool: + for idx, sect in enumerate(reversed(self.all_sections)): + if sect.kind == kind: + pos = len(self.all_sections) - idx - 1 + if after: + pos += 1 + self.all_sections.insert(pos, new_sect) + return True + return False + + if any(s.kind == QAPIDoc.Kind.RETURNS for s in self.all_sections): + return + + # Stub "Returns" section for undocumented returns value + stub = QAPIDoc.Section(info, QAPIDoc.Kind.RETURNS) + + if any(_insert_near_kind(kind, stub, after) for kind, after in ( + # 1. If arguments, right after those. + (QAPIDoc.Kind.MEMBER, True), + # 2. Elif errors, right *before* those. + (QAPIDoc.Kind.ERRORS, False), + # 3. Elif features, right *before* those. + (QAPIDoc.Kind.FEATURE, False), + )): + return + + # Otherwise, it should go right after the intro. The intro + # is always the first section and is always present (even + # when empty), so we can insert directly at index=1 blindly. + self.all_sections.insert(1, stub) + def check_expr(self, expr: QAPIExpression) -> None: if 'command' in expr: if self.returns and 'returns' not in expr: diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py index cbe3b5aa91..3abddea352 100644 --- a/scripts/qapi/schema.py +++ b/scripts/qapi/schema.py @@ -1062,6 +1062,9 @@ def connect_doc(self, doc: Optional[QAPIDoc] = None) -> None: if self.arg_type and self.arg_type.is_implicit(): self.arg_type.connect_doc(doc) + if self.ret_type and self.info: + doc.ensure_returns(self.info) + def visit(self, visitor: QAPISchemaVisitor) -> None: super().visit(visitor) visitor.visit_command( From 0462da9d6b1918c741c632f57d743d5851ec5983 Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:10:44 -0400 Subject: [PATCH 10/29] qapi: remove trivial "Returns:" sections The new qapidoc.py can generate "Returns" statements with type information just fine, so we can remove it from the source where it doesn't add anything particularly novel or helpful and just repeats the type info. This patch is fairly "gentle" and doesn't aggressively touch other "Returns" lines that could be rephrased to omit repeating type information; it only removes lines that appear appropriate to wholly remove. To help facilitate auto-generated placement, a few doc blocks have a "TODO:" line inserted to help the placement algorithm differentiate the introductory paragraph(s) from the rest of the documentation. The auto-generated returns are in the exact same spot, except for query-migrationthreads, query-machines, and x-query-virtio-queue-element. These auto-generation moves to a better spot. Signed-off-by: John Snow Message-ID: <20250711051045.51110-4-jsnow@redhat.com> Reviewed-by: Markus Armbruster [Two more Returns: removed, commit message amended to explain auto-generated returns generated into a different spot] Signed-off-by: Markus Armbruster --- qapi/audio.json | 2 -- qapi/block-core.json | 8 -------- qapi/char.json | 8 -------- qapi/cryptodev.json | 2 -- qapi/machine.json | 24 ------------------------ qapi/migration.json | 12 ++---------- qapi/misc-arm.json | 2 -- qapi/misc-i386.json | 10 ---------- qapi/misc.json | 7 ------- qapi/rocker.json | 4 ---- qapi/run-state.json | 2 -- qapi/tpm.json | 4 ---- qapi/ui.json | 8 -------- qapi/virtio.json | 2 -- qapi/yank.json | 2 +- 15 files changed, 3 insertions(+), 94 deletions(-) diff --git a/qapi/audio.json b/qapi/audio.json index 6a22ca384a..53142080f7 100644 --- a/qapi/audio.json +++ b/qapi/audio.json @@ -537,8 +537,6 @@ # # Return information about audiodev configuration # -# Returns: array of @Audiodev -# # Since: 8.0 ## { 'command': 'query-audiodevs', diff --git a/qapi/block-core.json b/qapi/block-core.json index 8b413946ff..01bf41b8b0 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -1951,8 +1951,6 @@ # @flat: Omit the nested data about backing image ("backing-image" # key) if true. Default is false (Since 5.0) # -# Returns: the list of BlockDeviceInfo -# # Since: 2.0 # # .. qmp-example:: @@ -2465,9 +2463,6 @@ # # @unstable: This command is meant for debugging. # -# Returns: -# BlockDirtyBitmapSha256 -# # Errors: # - If @node is not a valid block device, DeviceNotFound # - If @name is not found or if hashing has failed, GenericError @@ -6203,9 +6198,6 @@ # # @name: optional the snapshot's name to be deleted # -# Returns: -# SnapshotInfo -# # Errors: # - If @device is not a valid block device, GenericError # - If snapshot not found, GenericError diff --git a/qapi/char.json b/qapi/char.json index f38d04986d..f0a53f742c 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -38,8 +38,6 @@ # # Return information about current character devices. # -# Returns: a list of @ChardevInfo -# # Since: 0.14 # # .. qmp-example:: @@ -84,8 +82,6 @@ # # Return information about character device backends. # -# Returns: a list of @ChardevBackendInfo -# # Since: 2.0 # # .. qmp-example:: @@ -774,8 +770,6 @@ # # @backend: backend type and parameters # -# Returns: ChardevReturn. -# # Since: 1.4 # # .. qmp-example:: @@ -814,8 +808,6 @@ # # @backend: new backend type and parameters # -# Returns: ChardevReturn. -# # Since: 2.10 # # .. qmp-example:: diff --git a/qapi/cryptodev.json b/qapi/cryptodev.json index 1f49e1822c..eb309c22f8 100644 --- a/qapi/cryptodev.json +++ b/qapi/cryptodev.json @@ -98,8 +98,6 @@ # # Return information about current crypto devices. # -# Returns: a list of @QCryptodevInfo -# # Since: 8.0 ## { 'command': 'query-cryptodev', 'returns': ['QCryptodevInfo']} diff --git a/qapi/machine.json b/qapi/machine.json index 2d6a137f21..2364893cba 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -103,8 +103,6 @@ # # Return information about all virtual CPUs. # -# Returns: list of @CpuInfoFast -# # Since: 2.12 # # .. qmp-example:: @@ -220,8 +218,6 @@ # # @unstable: Argument @compat-props is experimental. # -# Returns: a list of MachineInfo -# # Since: 1.2 # # .. qmp-example:: @@ -270,8 +266,6 @@ # # Return information on the current virtual machine. # -# Returns: CurrentMachineParams -# # Since: 4.0 ## { 'command': 'query-current-machine', 'returns': 'CurrentMachineParams' } @@ -293,8 +287,6 @@ # # Return information about the target for this QEMU # -# Returns: QemuTargetInfo -# # Since: 1.2 ## { 'command': 'query-target', 'returns': 'QemuTargetInfo' } @@ -318,8 +310,6 @@ # # Query the guest UUID information. # -# Returns: The @UuidInfo for the guest -# # Since: 0.14 # # .. qmp-example:: @@ -471,8 +461,6 @@ # # Return information about KVM acceleration # -# Returns: @KvmInfo -# # Since: 0.14 # # .. qmp-example:: @@ -934,8 +922,6 @@ # # Return information for all memory backends. # -# Returns: a list of @Memdev. -# # Since: 2.1 # # .. qmp-example:: @@ -1051,8 +1037,6 @@ # # TODO: Better documentation; currently there is none. # -# Returns: a list of HotpluggableCPU objects. -# # Since: 2.7 # # .. qmp-example:: @@ -1174,9 +1158,6 @@ # # Return information about the balloon device. # -# Returns: -# @BalloonInfo -# # Errors: # - If the balloon driver is enabled but not functional because # the KVM kernel module cannot support it, KVMMissingCap @@ -1240,9 +1221,6 @@ # Return the hv-balloon driver data contained in the last received # "STATUS" message from the guest. # -# Returns: -# @HvBalloonInfo -# # Errors: # - If no hv-balloon device is present, guest memory status # reporting is not enabled or no guest memory status report @@ -2260,8 +2238,6 @@ # # Return a list of supported virtual CPU definitions # -# Returns: a list of CpuDefinitionInfo -# # Since: 1.2 ## { 'command': 'query-cpu-definitions', 'returns': ['CpuDefinitionInfo'] } diff --git a/qapi/migration.json b/qapi/migration.json index 3bf97df5d8..57653160eb 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -326,8 +326,6 @@ # is active there will be another json-object with RAM migration # status. # -# Returns: @MigrationInfo -# # Since: 0.14 # # .. qmp-example:: @@ -577,8 +575,6 @@ # # Return information about the current migration capabilities status # -# Returns: @MigrationCapabilityStatus -# # Since: 1.2 # # .. qmp-example:: @@ -1364,8 +1360,6 @@ # # Return information about the current migration parameters # -# Returns: @MigrationParameters -# # Since: 2.4 # # .. qmp-example:: @@ -1946,7 +1940,7 @@ # # Query replication status while the vm is running. # -# Returns: A @ReplicationStatus object showing the status. +# TODO: This line is a hack to separate the example from the body # # .. qmp-example:: # @@ -2000,7 +1994,7 @@ # # Query COLO status while the vm is running. # -# Returns: A @COLOStatus object showing the status. +# TODO: This line is a hack to separate the example from the body # # .. qmp-example:: # @@ -2375,8 +2369,6 @@ # # @deprecated: This command is deprecated with no replacement yet. # -# Returns: @MigrationThreadInfo -# # Since: 7.2 ## { 'command': 'query-migrationthreads', diff --git a/qapi/misc-arm.json b/qapi/misc-arm.json index f5341372f5..f9dd743b52 100644 --- a/qapi/misc-arm.json +++ b/qapi/misc-arm.json @@ -36,8 +36,6 @@ # On non-ARM targets this command will report an error as the GIC # technology is not applicable. # -# Returns: a list of GICCapability objects. -# # Since: 2.6 # # .. qmp-example:: diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json index 24a2e143f6..5c3c9a14e0 100644 --- a/qapi/misc-i386.json +++ b/qapi/misc-i386.json @@ -132,8 +132,6 @@ # @enabled field is set to 'false' and the state of all other fields # is unspecified. # -# Returns: @SevInfo -# # Since: 2.12 # # .. qmp-example:: @@ -214,8 +212,6 @@ # # This is only supported on AMD X86 platforms with KVM enabled. # -# Returns: SevCapability objects. -# # Errors: # - If SEV is not available on the platform, GenericError # @@ -280,8 +276,6 @@ # @mnonce: a random 16 bytes value encoded in base64 (it will be # included in report) # -# Returns: SevAttestationReport objects. -# # Errors: # - If the attestation report is unavailable, either due to an # invalid guest configuration or because the guest has not @@ -343,8 +337,6 @@ # # Return information about configured SGX capabilities of guest # -# Returns: @SgxInfo -# # Since: 6.2 # # .. qmp-example:: @@ -362,8 +354,6 @@ # # Return information about SGX capabilities of host # -# Returns: @SgxInfo -# # Since: 6.2 # # .. qmp-example:: diff --git a/qapi/misc.json b/qapi/misc.json index a180c16db2..b19eb08606 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -58,8 +58,6 @@ # # Return the name information of a guest. # -# Returns: @NameInfo of the guest -# # Since: 0.14 # # .. qmp-example:: @@ -334,9 +332,6 @@ # # @opaque: A free-form string that can be used to describe the fd. # -# Returns: -# @AddfdInfo -# # Errors: # - If file descriptor was not received, GenericError # - If @fdset-id is a negative value, GenericError @@ -417,8 +412,6 @@ # # Return information describing all fd sets. # -# Returns: A list of @FdsetInfo -# # Since: 1.2 # # .. note:: The list of fd sets is shared by all monitor connections. diff --git a/qapi/rocker.json b/qapi/rocker.json index e494964952..5d2dbd2603 100644 --- a/qapi/rocker.json +++ b/qapi/rocker.json @@ -30,8 +30,6 @@ # # @name: switch name # -# Returns: @Rocker information -# # Since: 2.4 # # .. qmp-example:: @@ -100,8 +98,6 @@ # # @name: port name # -# Returns: a list of @RockerPort information -# # Since: 2.4 # # .. qmp-example:: diff --git a/qapi/run-state.json b/qapi/run-state.json index 083a3c5eb3..76f14569ff 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -121,8 +121,6 @@ # # Query the run status of the VM # -# Returns: @StatusInfo reflecting the VM -# # Since: 0.14 # # .. qmp-example:: diff --git a/qapi/tpm.json b/qapi/tpm.json index e66b107f1d..3f2850a573 100644 --- a/qapi/tpm.json +++ b/qapi/tpm.json @@ -29,8 +29,6 @@ # # Return a list of supported TPM models # -# Returns: a list of TpmModel -# # Since: 1.5 # # .. qmp-example:: @@ -60,8 +58,6 @@ # # Return a list of supported TPM types # -# Returns: a list of TpmType -# # Since: 1.5 # # .. qmp-example:: diff --git a/qapi/ui.json b/qapi/ui.json index f5e77ae19d..53489ab65f 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -328,8 +328,6 @@ # # Return information about the current SPICE server # -# Returns: @SpiceInfo -# # Since: 0.14 # # .. qmp-example:: @@ -660,8 +658,6 @@ # # Return information about the current VNC server # -# Returns: @VncInfo -# # Since: 0.14 # # .. qmp-example:: @@ -691,8 +687,6 @@ # # Return a list of vnc servers. The list can be empty. # -# Returns: a list of @VncInfo2 -# # Since: 2.3 ## { 'command': 'query-vnc-servers', 'returns': ['VncInfo2'], @@ -1570,8 +1564,6 @@ # # Return information about display configuration # -# Returns: @DisplayOptions -# # Since: 3.1 ## { 'command': 'query-display-options', diff --git a/qapi/virtio.json b/qapi/virtio.json index 3cac0774f7..f0753cde71 100644 --- a/qapi/virtio.json +++ b/qapi/virtio.json @@ -849,8 +849,6 @@ # # @unstable: This command is meant for debugging. # -# Returns: VirtioQueueElement information -# # Since: 7.2 # # .. qmp-example:: diff --git a/qapi/yank.json b/qapi/yank.json index d13a8e9117..c14de5229e 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -104,7 +104,7 @@ # # Query yank instances. See @YankInstance for more information. # -# Returns: list of @YankInstance +# TODO: This line is a hack to separate the example from the body # # .. qmp-example:: # From f7296f8de5c96c09452a0774435c1e5b512fab19 Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:10:45 -0400 Subject: [PATCH 11/29] qapi: rephrase return docs to avoid type name MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "Returns: " is rendered like "Return: – ". Mentioning the type in the description again is commonly redundant. Rephrase such descriptions not to. Well, I tried. Maybe not very hard. Sorry! Signed-off-by: John Snow Message-ID: <20250711051045.51110-5-jsnow@redhat.com> Acked-by: Markus Armbruster [Commit message amended to explain why] Signed-off-by: Markus Armbruster --- qapi/block-core.json | 6 +++--- qapi/block-export.json | 2 +- qapi/block.json | 2 +- qapi/control.json | 5 ++--- qapi/dump.json | 5 ++--- qapi/introspect.json | 6 +++--- qapi/job.json | 2 +- qapi/misc-i386.json | 2 +- qapi/misc.json | 5 ++--- qapi/net.json | 2 +- qapi/pci.json | 2 +- qapi/qdev.json | 3 +-- qapi/qom.json | 8 +++----- qapi/stats.json | 2 +- qapi/trace.json | 2 +- qapi/ui.json | 2 +- qapi/virtio.json | 6 +++--- 17 files changed, 28 insertions(+), 34 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 01bf41b8b0..848ebaff5a 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -764,7 +764,7 @@ # # Get a list of BlockInfo for all virtual block devices. # -# Returns: a list of @BlockInfo describing each virtual block device. +# Returns: a list describing each virtual block device. # Filter nodes that were created implicitly are skipped over. # # Since: 0.14 @@ -1169,7 +1169,7 @@ # nodes that were created implicitly are skipped over in this # mode. (Since 2.3) # -# Returns: A list of @BlockStats for each virtual block devices. +# Returns: A list of statistics for each virtual block device. # # Since: 0.14 # @@ -1441,7 +1441,7 @@ # # Return information about long-running block device operations. # -# Returns: a list of @BlockJobInfo for each active block job +# Returns: a list of job info for each active block job # # Since: 1.1 ## diff --git a/qapi/block-export.json b/qapi/block-export.json index 2241bfecf2..fb004e35fd 100644 --- a/qapi/block-export.json +++ b/qapi/block-export.json @@ -473,7 +473,7 @@ ## # @query-block-exports: # -# Returns: A list of BlockExportInfo describing all block exports +# Returns: A list describing all block exports # # Since: 5.2 ## diff --git a/qapi/block.json b/qapi/block.json index 2d54a81c36..f0436ce871 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -89,7 +89,7 @@ # Return a list of information about each persistent reservation # manager. # -# Returns: a list of @PRManagerInfo for each persistent reservation +# Returns: a list of manager info for each persistent reservation # manager # # Since: 3.0 diff --git a/qapi/control.json b/qapi/control.json index 5fed0701f8..931a860b30 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -95,8 +95,7 @@ # # Return the current version of QEMU. # -# Returns: A @VersionInfo object describing the current version of -# QEMU. +# Returns: An object describing the current version of QEMU. # # Since: 0.14 # @@ -133,7 +132,7 @@ # # Return a list of supported QMP commands by this server # -# Returns: A list of @CommandInfo for all supported commands +# Returns: A list of all supported commands # # Since: 0.14 # diff --git a/qapi/dump.json b/qapi/dump.json index 0642ca157b..dc92b53247 100644 --- a/qapi/dump.json +++ b/qapi/dump.json @@ -148,7 +148,7 @@ # # Query latest dump status. # -# Returns: A @DumpStatus object showing the dump status. +# Returns: An object showing the dump status. # # Since: 2.6 # @@ -199,8 +199,7 @@ # # Return the available formats for dump-guest-memory # -# Returns: A @DumpGuestMemoryCapability object listing available -# formats for dump-guest-memory +# Returns: An object listing available formats for dump-guest-memory # # Since: 2.0 # diff --git a/qapi/introspect.json b/qapi/introspect.json index 26d8839f19..be8511b067 100644 --- a/qapi/introspect.json +++ b/qapi/introspect.json @@ -36,10 +36,10 @@ # string into a specific enum or from one specific type into an # alternate that includes the original type alongside something else. # -# Returns: array of @SchemaInfo, where each element describes an -# entity in the ABI: command, event, type, ... +# Returns: an array where each element describes an entity in the ABI: +# command, event, type, ... # -# The order of the various SchemaInfo is unspecified; however, all +# The order of the various elements is unspecified; however, all # names are guaranteed to be unique (no name will be duplicated # with different meta-types). # diff --git a/qapi/job.json b/qapi/job.json index 16b280f52f..51a57c523e 100644 --- a/qapi/job.json +++ b/qapi/job.json @@ -297,7 +297,7 @@ # # Return information about jobs. # -# Returns: a list with a @JobInfo for each active job +# Returns: a list with info for each active job # # Since: 3.0 ## diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json index 5c3c9a14e0..282bd3627b 100644 --- a/qapi/misc-i386.json +++ b/qapi/misc-i386.json @@ -163,7 +163,7 @@ # 'sev-guest' confidential virtualization object. The launch # measurement for SEV-SNP guests is only available within the guest. # -# Returns: The @SevLaunchMeasureInfo for the guest +# Returns: The guest's SEV guest launch measurement info # # Errors: # - If the launch measurement is unavailable, either due to an diff --git a/qapi/misc.json b/qapi/misc.json index b19eb08606..7dbc29dbd6 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -107,7 +107,7 @@ # declared using the ``-object iothread`` command-line option. It # is always the main thread of the process. # -# Returns: a list of @IOThreadInfo for each iothread +# Returns: a list of info for each iothread # # Since: 2.0 # @@ -511,8 +511,7 @@ # # @option: option name # -# Returns: list of @CommandLineOptionInfo for all options (or for the -# given @option). +# Returns: list of objects for all options (or for the given @option). # # Errors: # - if the given @option doesn't exist diff --git a/qapi/net.json b/qapi/net.json index 3b03843c16..a266c6786e 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -847,7 +847,7 @@ # # @name: net client name # -# Returns: list of @RxFilterInfo for all NICs (or for the given NIC). +# Returns: list of info for all NICs (or for the given NIC). # # Errors: # - if the given @name doesn't exist diff --git a/qapi/pci.json b/qapi/pci.json index a8671cd9ac..418ea4fc93 100644 --- a/qapi/pci.json +++ b/qapi/pci.json @@ -177,7 +177,7 @@ # # Return information about the PCI bus topology of the guest. # -# Returns: a list of @PciInfo for each PCI bus. Each bus is +# Returns: a list of info for each PCI bus. Each bus is # represented by a json-object, which has a key with a json-array # of all PCI devices attached to it. Each device is represented # by a json-object. diff --git a/qapi/qdev.json b/qapi/qdev.json index 441ed518b8..6441357e00 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -19,8 +19,7 @@ # # @typename: the type name of a device # -# Returns: a list of ObjectPropertyInfo describing a devices -# properties +# Returns: a list describing a devices properties # # .. note:: Objects can create properties at runtime, for example to # describe links between different devices and/or objects. These diff --git a/qapi/qom.json b/qapi/qom.json index fbf94b9e09..aa09eddbf9 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -55,8 +55,7 @@ # @path: the path within the object model. See @qom-get for a # description of this parameter. # -# Returns: a list of @ObjectPropertyInfo that describe the properties -# of the object. +# Returns: a list that describe the properties of the object. # # Since: 1.2 # @@ -178,8 +177,7 @@ # # @abstract: if true, include abstract types in the results # -# Returns: a list of @ObjectTypeInfo or an empty list if no results -# are found +# Returns: a list of types, or an empty list if no results are found # # Since: 1.1 ## @@ -199,7 +197,7 @@ # describe links between different devices and/or objects. These # properties are not included in the output of this command. # -# Returns: a list of ObjectPropertyInfo describing object properties +# Returns: a list describing object properties # # Since: 2.12 ## diff --git a/qapi/stats.json b/qapi/stats.json index 78b88881ea..b63a7369dd 100644 --- a/qapi/stats.json +++ b/qapi/stats.json @@ -188,7 +188,7 @@ # The arguments are a StatsFilter and specify the provider and objects # to return statistics about. # -# Returns: a list of StatsResult, one for each provider and object +# Returns: a list of statistics, one for each provider and object # (e.g., for each vCPU). # # Since: 7.1 diff --git a/qapi/trace.json b/qapi/trace.json index d08c9c6a88..de369dae6b 100644 --- a/qapi/trace.json +++ b/qapi/trace.json @@ -49,7 +49,7 @@ # # @name: Event name pattern (case-sensitive glob). # -# Returns: a list of @TraceEventInfo for the matching events +# Returns: a list of info for the matching events # # Since: 2.2 # diff --git a/qapi/ui.json b/qapi/ui.json index 53489ab65f..b48266c458 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -822,7 +822,7 @@ # # Return information about each active mouse device # -# Returns: a list of @MouseInfo for each device +# Returns: a list of info for each device # # Since: 0.14 # diff --git a/qapi/virtio.json b/qapi/virtio.json index f0753cde71..2e23512085 100644 --- a/qapi/virtio.json +++ b/qapi/virtio.json @@ -201,7 +201,7 @@ # # @unstable: This command is meant for debugging. # -# Returns: VirtioStatus of the virtio device +# Returns: Status of the virtio device # # Since: 7.2 # @@ -565,7 +565,7 @@ # # @unstable: This command is meant for debugging. # -# Returns: VirtQueueStatus of the VirtQueue +# Returns: Status of the queue # # .. note:: last_avail_idx will not be displayed in the case where the # selected VirtIODevice has a running vhost device and the @@ -700,7 +700,7 @@ # # @unstable: This command is meant for debugging. # -# Returns: VirtVhostQueueStatus of the vhost_virtqueue +# Returns: Status of the vhost_virtqueue # # Since: 7.2 # From 95b3be1965779e77a12a95d531914fa0fecc24ec Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:39:48 -0400 Subject: [PATCH 12/29] qapi: add cross-references to acpi.json Signed-off-by: John Snow Message-ID: <20250711054005.60969-2-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/acpi.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qapi/acpi.json b/qapi/acpi.json index 90f8f564fd..906b3687a5 100644 --- a/qapi/acpi.json +++ b/qapi/acpi.json @@ -108,7 +108,7 @@ ## # @query-acpi-ospm-status: # -# Return a list of ACPIOSTInfo for devices that support status +# Return a list of `ACPIOSTInfo` for devices that support status # reporting via ACPI _OST method. # # Since: 2.1 From a724defe3213999db735496daee94abb52e93f43 Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:39:49 -0400 Subject: [PATCH 13/29] qapi: add cross-references to authz.json Signed-off-by: John Snow Message-ID: <20250711054005.60969-3-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/authz.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qapi/authz.json b/qapi/authz.json index ad1b4b3af0..bc1123cc05 100644 --- a/qapi/authz.json +++ b/qapi/authz.json @@ -77,7 +77,7 @@ # Properties for authz-listfile objects. # # @filename: File name to load the configuration from. The file must -# contain valid JSON for AuthZListProperties. +# contain valid JSON for `AuthZListProperties`. # # @refresh: If true, inotify is used to monitor the file, # automatically reloading changes. If an error occurs during From a3763337ad0f4e6252abc894a8bbced11ddf3998 Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:39:50 -0400 Subject: [PATCH 14/29] qapi: add cross-references to block layer Signed-off-by: John Snow Message-ID: <20250711054005.60969-4-jsnow@redhat.com> Reviewed-by: Markus Armbruster [Two unwanted cross-references dropped] Signed-off-by: Markus Armbruster --- qapi/block-core.json | 184 ++++++++++++++++++++--------------------- qapi/block-export.json | 36 ++++---- qapi/block.json | 14 ++-- qapi/transaction.json | 12 +-- 4 files changed, 123 insertions(+), 123 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 848ebaff5a..25b57919a7 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -32,7 +32,7 @@ # @icount: Current instruction count. Appears when execution # record/replay is enabled. Used for "time-traveling" to match # the moment in the recorded execution with the snapshots. This -# counter may be obtained through @query-replay command +# counter may be obtained through `query-replay` command # (since 5.2) # # Since: 1.3 @@ -224,7 +224,7 @@ { 'struct': 'ImageInfoSpecificLUKSWrapper', 'data': { 'data': 'QCryptoBlockInfoLUKS' } } # If we need to add block driver specific parameters for -# LUKS in future, then we'll subclass QCryptoBlockInfoLUKS +# LUKS in future, then we'll subclass `QCryptoBlockInfoLUKS` # to define a ImageInfoSpecificLUKS ## @@ -333,7 +333,7 @@ # node, annotated with information about that node in relation to its # parent. # -# @name: Child name of the root node in the BlockGraphInfo struct, in +# @name: Child name of the root node in the `BlockGraphInfo` struct, in # its role as the child of some undescribed parent node # # @info: Block graph information starting at this node @@ -350,7 +350,7 @@ # @BlockGraphInfo: # # Information about all nodes in a block (sub)graph in the form of -# BlockNodeInfo data. The base BlockNodeInfo struct contains the +# `BlockNodeInfo` data. The base `BlockNodeInfo` struct contains the # information for the (sub)graph's root node. # # @children: Array of links to this node's child nodes' information @@ -615,7 +615,7 @@ # @inconsistent: true if this is a persistent bitmap that was # improperly stored. Implies @persistent to be true; @recording # and @busy to be false. This bitmap cannot be used. To remove -# it, use @block-dirty-bitmap-remove. (Since 4.0) +# it, use `block-dirty-bitmap-remove`. (Since 4.0) # # Since: 1.3 ## @@ -710,12 +710,12 @@ # @tray_open: True if the device's tray is open (only present if it # has a tray) # -# @io-status: @BlockDeviceIoStatus. Only present if the device +# @io-status: `BlockDeviceIoStatus`. Only present if the device # supports it and the VM is configured to stop on errors # (supported device models: virtio-blk, IDE, SCSI except # scsi-generic) # -# @inserted: @BlockDeviceInfo describing the device if media is +# @inserted: `BlockDeviceInfo` describing the device if media is # present # # Since: 0.14 @@ -762,7 +762,7 @@ ## # @query-block: # -# Get a list of BlockInfo for all virtual block devices. +# Get a list of `BlockInfo` for all virtual block devices. # # Returns: a list describing each virtual block device. # Filter nodes that were created implicitly are skipped over. @@ -1027,14 +1027,14 @@ # @timed_stats: Statistics specific to the set of previously defined # intervals of time (Since 2.5) # -# @rd_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0) +# @rd_latency_histogram: `BlockLatencyHistogramInfo`. (Since 4.0) # -# @wr_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0) +# @wr_latency_histogram: `BlockLatencyHistogramInfo`. (Since 4.0) # -# @zone_append_latency_histogram: @BlockLatencyHistogramInfo. +# @zone_append_latency_histogram: `BlockLatencyHistogramInfo`. # (since 8.1) # -# @flush_latency_histogram: @BlockLatencyHistogramInfo. (Since 4.0) +# @flush_latency_histogram: `BlockLatencyHistogramInfo`. (Since 4.0) # # Since: 0.14 ## @@ -1135,7 +1135,7 @@ # @qdev: The qdev ID, or if no ID is assigned, the QOM path of the # block device. (since 3.0) # -# @stats: A @BlockDeviceStats for the device. +# @stats: A `BlockDeviceStats` for the device. # # @driver-specific: Optional driver-specific stats. (Since 4.2) # @@ -1159,7 +1159,7 @@ ## # @query-blockstats: # -# Query the @BlockStats for all virtual block devices. +# Query the `BlockStats` for all virtual block devices. # # @query-nodes: If true, the command will query all the block nodes # that have a node name, in a list which will include "parent" @@ -1290,8 +1290,8 @@ # @report: for guest operations, report the error to the guest; for # jobs, cancel the job # -# @ignore: ignore the error, only report a QMP event (BLOCK_IO_ERROR -# or BLOCK_JOB_ERROR). The backup, mirror and commit block jobs +# @ignore: ignore the error, only report a QMP event (`BLOCK_IO_ERROR` +# or `BLOCK_JOB_ERROR`). The backup, mirror and commit block jobs # retry the failing request later and may still complete # successfully. The stream block job continues to stream and will # complete with an error. @@ -1324,7 +1324,7 @@ # (since: 2.4) # # @bitmap: only copy data described by the dirty bitmap. Behavior on -# completion is determined by the BitmapSyncMode. (since: 4.2) +# completion is determined by the `BitmapSyncMode`. (since: 4.2) # # Since: 1.3 ## @@ -1531,7 +1531,7 @@ # @overlay: reference to the existing block device that will become # the overlay of @node, as part of taking the snapshot. It must # not have a current backing file (this can be achieved by passing -# "backing": null to blockdev-add). +# "backing": null to `blockdev-add`). # # Since: 2.5 ## @@ -1586,7 +1586,7 @@ # @bitmap: The name of a dirty bitmap to use. Must be present if sync # is "bitmap" or "incremental". Can be present if sync is "full" # or "top". Must not be present otherwise. -# (Since 2.4 (drive-backup), 3.1 (blockdev-backup)) +# (Since 2.4 (`drive-backup`), 3.1 (`blockdev-backup`)) # # @bitmap-mode: Specifies the type of data the bitmap should contain # after the operation concludes. Must be present if a bitmap was @@ -1597,7 +1597,7 @@ # # @on-source-error: the action to take on an error on the source, # default 'report'. 'stop' and 'enospc' can only be used if the -# block device supports io-status (see BlockInfo). +# block device supports io-status (see `BlockInfo`). # # @on-target-error: the action to take on an error on the target, # default 'report' (no limitations, since this applies to a @@ -1607,14 +1607,14 @@ # copy-before-write jobs; defaults to break-guest-write. (Since 10.1) # # @auto-finalize: When false, this job will wait in a PENDING state -# after it has finished its work, waiting for @job-finalize before +# after it has finished its work, waiting for `job-finalize` before # making any block graph changes. When true, this job will # automatically perform its abort or commit actions. Defaults to # true. (Since 2.12) # # @auto-dismiss: When false, this job will wait in a CONCLUDED state # after it has completely ceased all work, and awaits -# @job-dismiss. When true, this job will automatically disappear +# `job-dismiss`. When true, this job will automatically disappear # without user intervention. Defaults to true. (Since 2.12) # # @filter-node-name: the node name that should be assigned to the @@ -1720,7 +1720,7 @@ # # @allow-write-only-overlay: If present, the check whether this # operation is safe was relaxed so that it can be used to change -# backing file of a destination of a blockdev-mirror. (since 5.0) +# backing file of a destination of a `blockdev-mirror`. (since 5.0) # # Since: 2.5 # @@ -1785,7 +1785,7 @@ # If top == base, that is an error. If top has no overlays on top of # it, or if it is in use by a writer, the job will not be completed by # itself. The user needs to complete the job with the -# job-complete command after getting the ready event. (Since 2.0) +# `job-complete` command after getting the ready event. (Since 2.0) # # If the base image is smaller than top, then the base image will be # resized to be the same size as top. If top is smaller than the base @@ -1847,14 +1847,14 @@ # autogenerated. (Since: 2.9) # # @auto-finalize: When false, this job will wait in a PENDING state -# after it has finished its work, waiting for @job-finalize before +# after it has finished its work, waiting for `job-finalize` before # making any block graph changes. When true, this job will # automatically perform its abort or commit actions. Defaults to # true. (Since 3.1) # # @auto-dismiss: When false, this job will wait in a CONCLUDED state # after it has completely ceased all work, and awaits -# @job-dismiss. When true, this job will automatically disappear +# `job-dismiss`. When true, this job will automatically disappear # without user intervention. Defaults to true. (Since 3.1) # # Features: @@ -1890,14 +1890,14 @@ # @drive-backup: # # Start a point-in-time copy of a block device to a new destination. -# The status of ongoing drive-backup operations can be checked with -# query-block-jobs where the BlockJobInfo.type field has the value +# The status of ongoing `drive-backup` operations can be checked with +# `query-block-jobs` where the `BlockJobInfo`.type field has the value # 'backup'. The operation can be stopped before it has completed -# using the job-cancel or block-job-cancel command. +# using the `job-cancel` or `block-job-cancel` command. # # Features: # -# @deprecated: This command is deprecated. Use @blockdev-backup +# @deprecated: This command is deprecated. Use `blockdev-backup` # instead. # # Errors: @@ -1921,10 +1921,10 @@ # @blockdev-backup: # # Start a point-in-time copy of a block device to a new destination. -# The status of ongoing blockdev-backup operations can be checked with -# query-block-jobs where the BlockJobInfo.type field has the value +# The status of ongoing `blockdev-backup` operations can be checked with +# `query-block-jobs` where the `BlockJobInfo`.type field has the value # 'backup'. The operation can be stopped before it has completed -# using the job-cancel or block-job-cancel command. +# using the `job-cancel` or `block-job-cancel` command. # # Errors: # - If @device is not a valid block device, DeviceNotFound @@ -2025,7 +2025,7 @@ # @XDbgBlockGraphNode: # # @id: Block graph node identifier. This @id is generated only for -# x-debug-query-block-graph and does not relate to any other +# `x-debug-query-block-graph` and does not relate to any other # identifiers in QEMU. # # @type: Type of graph node. Can be one of block-backend, block-job @@ -2074,7 +2074,7 @@ ## # @XDbgBlockGraphEdge: # -# Block Graph edge description for x-debug-query-block-graph. +# Block Graph edge description for `x-debug-query-block-graph`. # # @parent: parent id # @@ -2192,7 +2192,7 @@ # # @on-source-error: the action to take on an error on the source, # default 'report'. 'stop' and 'enospc' can only be used if the -# block device supports io-status (see BlockInfo). +# block device supports io-status (see `BlockInfo`). # # @on-target-error: the action to take on an error on the target, # default 'report' (no limitations, since this applies to a @@ -2208,14 +2208,14 @@ # 'background' (Since: 3.0) # # @auto-finalize: When false, this job will wait in a PENDING state -# after it has finished its work, waiting for @job-finalize before +# after it has finished its work, waiting for `job-finalize` before # making any block graph changes. When true, this job will # automatically perform its abort or commit actions. Defaults to # true. (Since 3.1) # # @auto-dismiss: When false, this job will wait in a CONCLUDED state # after it has completely ceased all work, and awaits -# @job-dismiss. When true, this job will automatically disappear +# `job-dismiss`. When true, this job will automatically disappear # without user intervention. Defaults to true. (Since 3.1) # # Since: 1.3 @@ -2250,16 +2250,16 @@ # @name: name of the dirty bitmap (must be less than 1024 bytes) # # @granularity: the bitmap granularity, default is 64k for -# block-dirty-bitmap-add +# `block-dirty-bitmap-add` # # @persistent: the bitmap is persistent, i.e. it will be saved to the # corresponding block device image file on its close. For now # only Qcow2 disks support persistent bitmaps. Default is false -# for block-dirty-bitmap-add. (Since: 2.10) +# for `block-dirty-bitmap-add`. (Since: 2.10) # # @disabled: the bitmap is created in the disabled state, which means # that it will not track drive changes. The bitmap may be enabled -# with block-dirty-bitmap-enable. Default is false. (Since: 4.0) +# with `block-dirty-bitmap-enable`. Default is false. (Since: 4.0) # # Since: 2.4 ## @@ -2289,7 +2289,7 @@ # @target: name of the destination dirty bitmap # # @bitmaps: name(s) of the source dirty bitmap(s) at @node and/or -# fully specified BlockDirtyBitmap elements. The latter are +# fully specified `BlockDirtyBitmap` elements. The latter are # supported since 4.1. # # Since: 4.0 @@ -2324,7 +2324,7 @@ # @block-dirty-bitmap-remove: # # Stop write tracking and remove the dirty bitmap that was created -# with block-dirty-bitmap-add. If the bitmap is persistent, remove it +# with `block-dirty-bitmap-add`. If the bitmap is persistent, remove it # from its storage too. # # Errors: @@ -2508,7 +2508,7 @@ # # @on-source-error: the action to take on an error on the source, # default 'report'. 'stop' and 'enospc' can only be used if the -# block device supports io-status (see BlockInfo). +# block device supports io-status (see `BlockInfo`). # # @on-target-error: the action to take on an error on the target, # default 'report' (no limitations, since this applies to a @@ -2523,14 +2523,14 @@ # 'background' (Since: 3.0) # # @auto-finalize: When false, this job will wait in a PENDING state -# after it has finished its work, waiting for @job-finalize before +# after it has finished its work, waiting for `job-finalize` before # making any block graph changes. When true, this job will # automatically perform its abort or commit actions. Defaults to # true. (Since 3.1) # # @auto-dismiss: When false, this job will wait in a CONCLUDED state # after it has completely ceased all work, and awaits -# @job-dismiss. When true, this job will automatically disappear +# `job-dismiss`. When true, this job will automatically disappear # without user intervention. Defaults to true. (Since 3.1) # # @target-is-zero: Assume the destination reads as all zeroes before @@ -2778,9 +2778,9 @@ # The block streaming operation is performed in the background until # the entire backing file has been copied. This command returns # immediately once streaming has started. The status of ongoing block -# streaming operations can be checked with query-block-jobs. The +# streaming operations can be checked with `query-block-jobs`. The # operation can be stopped before it has completed using the -# job-cancel or block-job-cancel command. +# `job-cancel` or `block-job-cancel` command. # # The node that receives the data is called the top image, can be # located in any part of the chain (but always above the base image; @@ -2799,9 +2799,9 @@ # will be the new backing file. # # On successful completion the image file is updated to drop the -# backing file and the BLOCK_JOB_COMPLETED event is emitted. +# backing file and the `BLOCK_JOB_COMPLETED` event is emitted. # -# In case @device is a filter node, block-stream modifies the first +# In case @device is a filter node, `block-stream` modifies the first # non-filter overlay node below it to point to the new backing node # instead of modifying @device itself. # @@ -2842,7 +2842,7 @@ # # @on-error: the action to take on an error (default report). 'stop' # and 'enospc' can only be used if the block device supports -# io-status (see BlockInfo). (Since 1.3) +# io-status (see `BlockInfo`). (Since 1.3) # # @filter-node-name: the node name that should be assigned to the # filter driver that the stream job inserts into the graph above @@ -2850,14 +2850,14 @@ # autogenerated. (Since: 6.0) # # @auto-finalize: When false, this job will wait in a PENDING state -# after it has finished its work, waiting for @job-finalize before +# after it has finished its work, waiting for `job-finalize` before # making any block graph changes. When true, this job will # automatically perform its abort or commit actions. Defaults to # true. (Since 3.1) # # @auto-dismiss: When false, this job will wait in a CONCLUDED state # after it has completely ceased all work, and awaits -# @job-dismiss. When true, this job will automatically disappear +# `job-dismiss`. When true, this job will automatically disappear # without user intervention. Defaults to true. (Since 3.1) # # Errors: @@ -2918,13 +2918,13 @@ # command if no operation is in progress. # # The operation will cancel as soon as possible and then emit the -# BLOCK_JOB_CANCELLED event. Before that happens the job is still -# visible when enumerated using query-block-jobs. +# `BLOCK_JOB_CANCELLED` event. Before that happens the job is still +# visible when enumerated using `query-block-jobs`. # -# Note that if you issue 'block-job-cancel' after 'drive-mirror' has -# indicated (via the event BLOCK_JOB_READY) that the source and +# Note that if you issue `block-job-cancel` after `drive-mirror` has +# indicated (via the event `BLOCK_JOB_READY`) that the source and # destination are synchronized, then the event triggered by this -# command changes to BLOCK_JOB_COMPLETED, to indicate that the +# command changes to `BLOCK_JOB_COMPLETED`, to indicate that the # mirroring has ended and the destination now has a point-in-time copy # tied to the time of the cancellation. # @@ -2938,7 +2938,7 @@ # values. # # @force: If true, and the job has already emitted the event -# BLOCK_JOB_READY, abandon the job immediately (even if it is +# `BLOCK_JOB_READY`, abandon the job immediately (even if it is # paused) instead of waiting for the destination to complete its # final synchronization (since 1.3) # @@ -2961,7 +2961,7 @@ # # The job will pause as soon as possible, which means transitioning # into the PAUSED state if it was RUNNING, or into STANDBY if it was -# READY. The corresponding JOB_STATUS_CHANGE event will be emitted. +# READY. The corresponding `JOB_STATUS_CHANGE` event will be emitted. # # Cancelling a paused job automatically resumes it. # @@ -2971,7 +2971,7 @@ # # Features: # -# @deprecated: This command is deprecated. Use @job-pause +# @deprecated: This command is deprecated. Use `job-pause` # instead. # # Errors: @@ -3000,7 +3000,7 @@ # # Features: # -# @deprecated: This command is deprecated. Use @job-resume +# @deprecated: This command is deprecated. Use `job-resume` # instead. # # Errors: @@ -3021,14 +3021,14 @@ # # This is supported only for drive mirroring, where it also switches # the device to write to the target path only. Note that drive -# mirroring includes drive-mirror, blockdev-mirror and block-commit +# mirroring includes `drive-mirror`, `blockdev-mirror` and `block-commit` # job (only in case of "active commit", when the node being commited # is used by the guest). The ability to complete is signaled with a -# BLOCK_JOB_READY event. +# `BLOCK_JOB_READY` event. # # This command completes an active background block operation # synchronously. The ordering of this command's return with the -# BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error +# `BLOCK_JOB_COMPLETED` event is not defined. Note that if an I/O error # occurs during the processing of this command: 1) the command itself # will fail; 2) the error will be processed according to the # rerror/werror arguments that were specified when starting the @@ -3040,7 +3040,7 @@ # # Features: # -# @deprecated: This command is deprecated. Use @job-complete +# @deprecated: This command is deprecated. Use `job-complete` # instead. # # Errors: @@ -3059,21 +3059,21 @@ # Deletes a job that is in the CONCLUDED state. This command only # needs to be run explicitly for jobs that don't have automatic # dismiss enabled. In turn, automatic dismiss may be enabled only -# for jobs that have @auto-dismiss option, which are drive-backup, -# blockdev-backup, drive-mirror, blockdev-mirror, block-commit and -# block-stream. @auto-dismiss is enabled by default for these +# for jobs that have @auto-dismiss option, which are `drive-backup`, +# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit` and +# `block-stream`. @auto-dismiss is enabled by default for these # jobs. # # This command will refuse to operate on any job that has not yet # reached its terminal state, CONCLUDED. For jobs that make use of -# the BLOCK_JOB_READY event, job-cancel, block-job-cancel or -# job-complete will still need to be used as appropriate. +# the `BLOCK_JOB_READY` event, `job-cancel`, `block-job-cancel` or +# `job-complete` will still need to be used as appropriate. # # @id: The job identifier. # # Features: # -# @deprecated: This command is deprecated. Use @job-dismiss +# @deprecated: This command is deprecated. Use `job-dismiss` # instead. # # Since: 2.12 @@ -3101,7 +3101,7 @@ # # Features: # -# @deprecated: This command is deprecated. Use @job-finalize +# @deprecated: This command is deprecated. Use `job-finalize` # instead. # # Since: 2.12 @@ -3173,7 +3173,7 @@ # @on: Enabled # # @unmap: Enabled and even try to unmap blocks if possible. This -# requires also that @BlockdevDiscardOptions is set to unmap for +# requires also that `BlockdevDiscardOptions` is set to unmap for # this device. # # Since: 2.1 @@ -4715,7 +4715,7 @@ # @driver: block driver name # # @node-name: the node name of the new node. This option is required -# on the top level of blockdev-add. Valid node names start with +# on the top level of `blockdev-add`. Valid node names start with # an alphabetic character and may contain only alphanumeric # characters, '-', '.' and '_'. Their maximum length is 31 # characters. (Since 2.0) @@ -4919,7 +4919,7 @@ # cancelled. # # The command receives a list of block devices to reopen. For each -# one of them, the top-level @node-name option (from BlockdevOptions) +# one of them, the top-level @node-name option (from `BlockdevOptions`) # must be specified and is used to select the block device to be # reopened. Other @node-name options must be either omitted or set to # the current name of the appropriate node. This command won't change @@ -4928,7 +4928,7 @@ # In the case of options that refer to child nodes, the behavior of # this command depends on the value: # -# 1) A set of options (BlockdevOptions): the child is reopened with +# 1) A set of options (`BlockdevOptions`): the child is reopened with # the specified set of options. # # 2) A reference to the current child: the child is reopened using @@ -4942,7 +4942,7 @@ # Options (1) and (2) are supported in all cases. Option (3) is # supported for @file and @backing, and option (4) for @backing only. # -# Unlike with blockdev-add, the @backing option must always be present +# 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. @@ -4956,7 +4956,7 @@ ## # @blockdev-del: # -# Deletes a block device that has been added using blockdev-add. The +# Deletes a block device that has been added using `blockdev-add`. The # command will fail if the node is attached to a device or is # otherwise being used. # @@ -5511,7 +5511,7 @@ # @blockdev-create: # # Starts a job to create an image format on a given node. The job is -# automatically finalized, but a manual job-dismiss is required. +# automatically finalized, but a manual `job-dismiss` is required. # # @job-id: Identifier for the newly created job. # @@ -5571,7 +5571,7 @@ # # Starts a job to amend format specific options of an existing open # block device. The job is automatically finalized, but a manual -# job-dismiss is required. +# `job-dismiss` is required. # # @job-id: Identifier for the newly created job. # @@ -5640,10 +5640,10 @@ # # @fatal: if set, the image is marked corrupt and therefore unusable # after this event and must be repaired (Since 2.2; before, every -# BLOCK_IMAGE_CORRUPTED event was fatal) +# `BLOCK_IMAGE_CORRUPTED` event was fatal) # -# .. note:: If action is "stop", a STOP event will eventually follow -# the BLOCK_IO_ERROR event. +# .. note:: If action is "stop", a `STOP` event will eventually follow +# the `BLOCK_IO_ERROR` event. # # .. qmp-example:: # @@ -5684,15 +5684,15 @@ # # @nospace: true if I/O error was caused due to a no-space condition. # This key is only present if query-block's io-status is present, -# please see query-block documentation for more information +# please see `query-block` documentation for more information # (since: 2.2) # # @reason: human readable string describing the error cause. (This # field is a debugging aid for humans, it should not be parsed by # applications) (since: 2.2) # -# .. note:: If action is "stop", a STOP event will eventually follow -# the BLOCK_IO_ERROR event. +# .. note:: If action is "stop", a `STOP` event will eventually follow +# the `BLOCK_IO_ERROR` event. # # .. note:: This event is rate-limited. # @@ -5834,7 +5834,7 @@ # @speed: rate limit, bytes per second # # .. note:: The "ready to complete" status is always reset by a -# @BLOCK_JOB_ERROR event. +# `BLOCK_JOB_ERROR` event. # # Since: 1.3 # @@ -5856,7 +5856,7 @@ # @BLOCK_JOB_PENDING: # # Emitted when a block job is awaiting explicit authorization to -# finalize graph changes via @job-finalize. If this job is part +# finalize graph changes via `job-finalize`. If this job is part # of a transaction, it will not emit this event until the transaction # has converged first. # @@ -5905,7 +5905,7 @@ # configured write threshold. For thin-provisioned devices, this # means the device should be extended to avoid pausing for disk # exhaustion. The event is one shot. Once triggered, it needs to be -# re-registered with another block-set-write-threshold command. +# re-registered with another `block-set-write-threshold` command. # # @node-name: graph node name on which the threshold was exceeded. # @@ -5976,7 +5976,7 @@ # # TODO: Removing children from a quorum node means introducing # gaps in the child indices. This cannot be represented in the -# 'children' list of BlockdevOptionsQuorum, as returned by +# 'children' list of `BlockdevOptionsQuorum`, as returned by # .bdrv_refresh_filename(). # # Since: 2.7 @@ -6189,7 +6189,7 @@ # Synchronously delete an internal snapshot of a block device, when # the format of the image used support it. The snapshot is identified # by name or id or both. One of the name or id is required. Return -# SnapshotInfo for the successfully deleted snapshot. +# `SnapshotInfo` for the successfully deleted snapshot. # # @device: the device name or node-name of a root node to delete the # snapshot from diff --git a/qapi/block-export.json b/qapi/block-export.json index fb004e35fd..6878b89dcf 100644 --- a/qapi/block-export.json +++ b/qapi/block-export.json @@ -38,9 +38,9 @@ ## # @NbdServerOptions: # -# Keep this type consistent with the NbdServerOptionsLegacy type. The -# only intended difference is using SocketAddress instead of -# SocketAddressLegacy. +# Keep this type consistent with the `NbdServerOptionsLegacy` type. The +# only intended difference is using `SocketAddress` instead of +# `SocketAddressLegacy`. # # @addr: Address on which to listen (since 4.2). ## @@ -51,9 +51,9 @@ ## # @NbdServerOptionsLegacy: # -# Keep this type consistent with the NbdServerOptions type. The only -# intended difference is using SocketAddressLegacy instead of -# SocketAddress. +# Keep this type consistent with the `NbdServerOptions` type. The only +# intended difference is using `SocketAddressLegacy` instead of +# `SocketAddress`. # # @addr: Address on which to listen (since 1.3). ## @@ -65,7 +65,7 @@ # @nbd-server-start: # # Start an NBD server listening on the given host and port. Block -# devices can then be exported using @nbd-server-add. The NBD server +# devices can then be exported using `nbd-server-add`. The NBD server # will present them as named exports; for example, another QEMU # instance could refer to them as "nbd:HOST:PORT:exportname=NAME". # @@ -81,8 +81,8 @@ ## # @BlockExportOptionsNbdBase: # -# An NBD block export (common options shared between nbd-server-add -# and the NBD branch of block-export-add). +# An NBD block export (common options shared between `nbd-server-add` +# and the NBD branch of `block-export-add`). # # @name: Export name. If unspecified, the @device parameter is used # as the export name. (Since 2.12) @@ -99,7 +99,7 @@ # @BlockExportOptionsNbd: # # An NBD block export (distinct options used in the NBD branch of -# block-export-add). +# `block-export-add`). # # @bitmaps: Also export each of the named dirty bitmaps reachable from # @device, so the NBD client can use NBD_OPT_SET_META_CONTEXT with @@ -125,7 +125,7 @@ # A vhost-user-blk block export. # # @addr: The vhost-user socket on which to listen. Both 'unix' and -# 'fd' SocketAddress types are supported. Passed fds must be UNIX +# 'fd' `SocketAddress` types are supported. Passed fds must be UNIX # domain sockets. # # @logical-block-size: Logical block size in bytes. Defaults to 512 @@ -217,7 +217,7 @@ ## # @NbdServerAddOptions: # -# An NBD block export, per legacy nbd-server-add command. +# An NBD block export, per legacy `nbd-server-add` command. # # @device: The device name or node name of the node to be exported # @@ -246,7 +246,7 @@ # # Features: # -# @deprecated: This command is deprecated. Use @block-export-add +# @deprecated: This command is deprecated. Use `block-export-add` # instead. # # Errors: @@ -289,12 +289,12 @@ # # @name: Block export id. # -# @mode: Mode of command operation. See @BlockExportRemoveMode +# @mode: Mode of command operation. See `BlockExportRemoveMode` # description. Default is 'safe'. # # Features: # -# @deprecated: This command is deprecated. Use @block-export-del +# @deprecated: This command is deprecated. Use `block-export-del` # instead. # # Errors: @@ -313,7 +313,7 @@ # @nbd-server-stop: # # Stop QEMU's embedded NBD server, and unregister all devices -# previously added via @nbd-server-add. +# previously added via `nbd-server-add`. # # Since: 1.3 ## @@ -422,7 +422,7 @@ # # @id: Block export id. # -# @mode: Mode of command operation. See @BlockExportRemoveMode +# @mode: Mode of command operation. See `BlockExportRemoveMode` # description. Default is 'safe'. # # Errors: @@ -460,7 +460,7 @@ # @node-name: The node name of the block node that is exported # # @shutting-down: True if the export is shutting down (e.g. after a -# block-export-del command, but before the shutdown has completed) +# `block-export-del` command, but before the shutdown has completed) # # Since: 5.2 ## diff --git a/qapi/block.json b/qapi/block.json index f0436ce871..46955bbb3e 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -140,7 +140,7 @@ # # If the tray was already open before, this will be a no-op. # -# Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There +# Once the tray opens, a `DEVICE_TRAY_MOVED` event is emitted. There # are cases in which no such event will be generated, these include: # # - if the guest has locked the tray, @force is false and the guest @@ -299,7 +299,7 @@ # @BlockdevChangeReadOnlyMode: # # Specifies the new read-only mode of a block device subject to the -# @blockdev-change-medium command. +# `blockdev-change-medium` command. # # @retain: Retains the current read-only mode # @@ -317,9 +317,9 @@ # # Changes the medium inserted into a block device by ejecting the # current medium and loading a new image file which is inserted as the -# new medium (this command combines blockdev-open-tray, -# blockdev-remove-medium, blockdev-insert-medium and -# blockdev-close-tray). +# new medium (this command combines `blockdev-open-tray`, +# `blockdev-remove-medium`, `blockdev-insert-medium` and +# `blockdev-close-tray`). # # @device: Block device name # @@ -334,7 +334,7 @@ # to 'retain' # # @force: if false (the default), an eject request through -# blockdev-open-tray will be sent to the guest if it has locked +# `blockdev-open-tray` will be sent to the guest if it has locked # the tray (and the tray will not be opened immediately); if true, # the tray will be opened regardless of whether it is locked. # (since 7.1) @@ -522,7 +522,7 @@ # @id: The name or QOM path of the guest device. # # @boundaries: list of interval boundary values (see description in -# BlockLatencyHistogramInfo definition). If specified, all +# `BlockLatencyHistogramInfo` definition). If specified, all # latency histograms are removed, and empty ones created for all # io types with intervals corresponding to @boundaries (except for # io types, for which specific boundaries are set through the diff --git a/qapi/transaction.json b/qapi/transaction.json index 927035f5a7..4b4eb09bf3 100644 --- a/qapi/transaction.json +++ b/qapi/transaction.json @@ -69,8 +69,8 @@ # # Features: # -# @deprecated: Member @drive-backup is deprecated. Use member -# @blockdev-backup instead. +# @deprecated: Member `drive-backup` is deprecated. Use member +# `blockdev-backup` instead. # # Since: 1.1 ## @@ -158,7 +158,7 @@ # @TransactionAction: # # A discriminated record of operations that can be performed with -# @transaction. +# `transaction`. # # @type: the operation to be performed # @@ -189,7 +189,7 @@ # # @completion-mode: Controls how jobs launched asynchronously by # Actions will complete or fail as a group. See -# @ActionCompletionMode for details. +# `ActionCompletionMode` for details. # # Since: 2.5 ## @@ -229,11 +229,11 @@ # in the transaction. When an I/O error occurs during deletion, the # user needs to fix it later with qemu-img or other command. # -# @actions: List of @TransactionAction; information needed for the +# @actions: List of `TransactionAction`; information needed for the # respective operations. # # @properties: structure of additional options to control the -# execution of the transaction. See @TransactionProperties for +# execution of the transaction. See `TransactionProperties` for # additional detail. # # Errors: From ed17e68732d2efa4dc813a02de0bbf68ed40775c Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:39:51 -0400 Subject: [PATCH 15/29] qapi: add cross-references to crypto.json Signed-off-by: John Snow Message-ID: <20250711054005.60969-5-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/crypto.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/qapi/crypto.json b/qapi/crypto.json index 21006de36c..ab6eda4c2f 100644 --- a/qapi/crypto.json +++ b/qapi/crypto.json @@ -591,9 +591,9 @@ # # Specific parameters for RSA algorithm. # -# @hash-alg: QCryptoHashAlgo +# @hash-alg: `QCryptoHashAlgo` # -# @padding-alg: QCryptoRSAPaddingAlgo +# @padding-alg: `QCryptoRSAPaddingAlgo` # # Since: 7.1 ## From dc79c02898dd5b2fdc9851f6c226421c701f6478 Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:39:52 -0400 Subject: [PATCH 16/29] qapi: add cross-references to dump.json Signed-off-by: John Snow Message-ID: <20250711054005.60969-6-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/dump.json | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/qapi/dump.json b/qapi/dump.json index dc92b53247..32c8c1f06e 100644 --- a/qapi/dump.json +++ b/qapi/dump.json @@ -112,7 +112,7 @@ # # Describe the status of a long-running background guest memory dump. # -# @none: no dump-guest-memory has started yet. +# @none: no `dump-guest-memory` has started yet. # # @active: there is one dump running in background. # @@ -128,9 +128,9 @@ ## # @DumpQueryResult: # -# The result format for 'query-dump'. +# The result format for `query-dump`. # -# @status: enum of @DumpStatus, which shows current dump status +# @status: enum of `DumpStatus`, which shows current dump status # # @completed: bytes written in latest dump (uncompressed) # @@ -186,7 +186,7 @@ ## # @DumpGuestMemoryCapability: # -# @formats: the available formats for dump-guest-memory +# @formats: the available formats for `dump-guest-memory` # # Since: 2.0 ## @@ -197,9 +197,9 @@ ## # @query-dump-guest-memory-capability: # -# Return the available formats for dump-guest-memory +# Return the available formats for `dump-guest-memory` # -# Returns: An object listing available formats for dump-guest-memory +# Returns: An object listing available formats for `dump-guest-memory` # # Since: 2.0 # From d1813fb4c4b052ec24814b7781431ee60bd57fdd Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:39:53 -0400 Subject: [PATCH 17/29] qapi: add cross-references to job.json Signed-off-by: John Snow Message-ID: <20250711054005.60969-7-jsnow@redhat.com> Reviewed-by: Markus Armbruster [Accidental line rewrap and an unwanted cross-refence dropped] Signed-off-by: Markus Armbruster --- qapi/job.json | 56 +++++++++++++++++++++++++-------------------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/qapi/job.json b/qapi/job.json index 51a57c523e..8b08350af2 100644 --- a/qapi/job.json +++ b/qapi/job.json @@ -12,26 +12,26 @@ # # Type of a background job. # -# @commit: block commit job type, see "block-commit" +# @commit: block commit job type, see `block-commit` # -# @stream: block stream job type, see "block-stream" +# @stream: block stream job type, see `block-stream` # -# @mirror: drive mirror job type, see "drive-mirror" +# @mirror: drive mirror job type, see `drive-mirror` # -# @backup: drive backup job type, see "drive-backup" +# @backup: drive backup job type, see `drive-backup` # -# @create: image creation job type, see "blockdev-create" (since 3.0) +# @create: image creation job type, see `blockdev-create` (since 3.0) # -# @amend: image options amend job type, see "x-blockdev-amend" +# @amend: image options amend job type, see `x-blockdev-amend` # (since 5.1) # -# @snapshot-load: snapshot load job type, see "snapshot-load" +# @snapshot-load: snapshot load job type, see `snapshot-load` # (since 6.0) # -# @snapshot-save: snapshot save job type, see "snapshot-save" +# @snapshot-save: snapshot save job type, see `snapshot-save` # (since 6.0) # -# @snapshot-delete: snapshot delete job type, see "snapshot-delete" +# @snapshot-delete: snapshot delete job type, see `snapshot-delete` # (since 6.0) # # Since: 1.7 @@ -67,7 +67,7 @@ # # @pending: The job has finished its work, but has finalization steps # that it needs to make prior to completing. These changes will -# require manual intervention via @job-finalize if auto-finalize +# require manual intervention via `job-finalize` if auto-finalize # was set to false. These pending changes may still fail. # # @aborting: The job is in the process of being aborted, and will @@ -77,7 +77,7 @@ # # @concluded: The job has finished all work. If auto-dismiss was set # to false, the job will remain in this state until it is -# dismissed via @job-dismiss. +# dismissed via `job-dismiss`. # # @null: The job is in the process of being dismantled. This state # should not ever be visible externally. @@ -93,21 +93,21 @@ # # Represents command verbs that can be applied to a job. # -# @cancel: see @job-cancel +# @cancel: see `job-cancel` # -# @pause: see @job-pause +# @pause: see `job-pause` # -# @resume: see @job-resume +# @resume: see `job-resume` # -# @set-speed: see @block-job-set-speed +# @set-speed: see `block-job-set-speed` # -# @complete: see @job-complete +# @complete: see `job-complete` # -# @dismiss: see @job-dismiss +# @dismiss: see `job-dismiss` # -# @finalize: see @job-finalize +# @finalize: see `job-finalize` # -# @change: see @block-job-change (since 8.2) +# @change: see `block-job-change` (since 8.2) # # Since: 2.12 ## @@ -140,7 +140,7 @@ # # The job will pause as soon as possible, which means transitioning # into the PAUSED state if it was RUNNING, or into STANDBY if it was -# READY. The corresponding JOB_STATUS_CHANGE event will be emitted. +# READY. The corresponding `JOB_STATUS_CHANGE` event will be emitted. # # Cancelling a paused job automatically resumes it. # @@ -175,7 +175,7 @@ # cancellation. # # The job will cancel as soon as possible and then emit a -# JOB_STATUS_CHANGE event. Usually, the status will change to +# `JOB_STATUS_CHANGE` event. Usually, the status will change to # ABORTING, but it is possible that a job successfully completes (e.g. # because it was almost done and there was no opportunity to cancel # earlier than completing the job) and transitions to PENDING instead. @@ -194,14 +194,14 @@ # # This is supported only for drive mirroring, where it also switches # the device to write to the target path only. Note that drive -# mirroring includes drive-mirror, blockdev-mirror and block-commit +# mirroring includes `drive-mirror`, `blockdev-mirror` and `block-commit` # job (only in case of "active commit", when the node being commited # is used by the guest). The ability to complete is signaled with a -# BLOCK_JOB_READY event. +# `BLOCK_JOB_READY` event. # # This command completes an active background block operation # synchronously. The ordering of this command's return with the -# BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error +# `BLOCK_JOB_COMPLETED` event is not defined. Note that if an I/O error # occurs during the processing of this command: 1) the command itself # will fail; 2) the error will be processed according to the # rerror/werror arguments that were specified when starting the @@ -219,14 +219,14 @@ # Deletes a job that is in the CONCLUDED state. This command only # needs to be run explicitly for jobs that don't have automatic # dismiss enabled. In turn, automatic dismiss may be enabled only -# for jobs that have @auto-dismiss option, which are drive-backup, -# blockdev-backup, drive-mirror, blockdev-mirror, block-commit and -# block-stream. @auto-dismiss is enabled by default for these +# for jobs that have @auto-dismiss option, which are `drive-backup`, +# `blockdev-backup`, `drive-mirror`, `blockdev-mirror`, `block-commit` and +# `block-stream`. @auto-dismiss is enabled by default for these # jobs. # # This command will refuse to operate on any job that has not yet # reached its terminal state, CONCLUDED. For jobs that make use of -# the JOB_READY event, job-cancel or job-complete will still need to +# the JOB_READY event, `job-cancel` or `job-complete` will still need to # be used as appropriate. # # @id: The job identifier. From 6082825e95cd1d3e638c1df68c05c8847cac5c08 Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:39:54 -0400 Subject: [PATCH 18/29] qapi: add cross-references to Machine core Signed-off-by: John Snow Message-ID: <20250711054005.60969-8-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/machine-common.json | 20 +++++----- qapi/machine.json | 80 ++++++++++++++++++++-------------------- 2 files changed, 50 insertions(+), 50 deletions(-) diff --git a/qapi/machine-common.json b/qapi/machine-common.json index 0f01599130..ed3d20a2fb 100644 --- a/qapi/machine-common.json +++ b/qapi/machine-common.json @@ -28,29 +28,29 @@ # # @thread: thread level, which would also be called SMT level or # logical processor level. The @threads option in -# SMPConfiguration is used to configure the topology of this +# `SMPConfiguration` is used to configure the topology of this # level. # -# @core: core level. The @cores option in SMPConfiguration is used +# @core: core level. The @cores option in `SMPConfiguration` is used # to configure the topology of this level. # -# @module: module level. The @modules option in SMPConfiguration is +# @module: module level. The @modules option in `SMPConfiguration` is # used to configure the topology of this level. # -# @cluster: cluster level. The @clusters option in SMPConfiguration +# @cluster: cluster level. The @clusters option in `SMPConfiguration` # is used to configure the topology of this level. # -# @die: die level. The @dies option in SMPConfiguration is used to +# @die: die level. The @dies option in `SMPConfiguration` is used to # configure the topology of this level. # # @socket: socket level, which would also be called package level. -# The @sockets option in SMPConfiguration is used to configure +# The @sockets option in `SMPConfiguration` is used to configure # the topology of this level. # -# @book: book level. The @books option in SMPConfiguration is used +# @book: book level. The @books option in `SMPConfiguration` is used # to configure the topology of this level. # -# @drawer: drawer level. The @drawers option in SMPConfiguration is +# @drawer: drawer level. The @drawers option in `SMPConfiguration` is # used to configure the topology of this level. # # @default: default level. Some architectures will have default @@ -104,9 +104,9 @@ ## # @SmpCachePropertiesWrapper: # -# List wrapper of SmpCacheProperties. +# List wrapper of `SmpCacheProperties`. # -# @caches: the list of SmpCacheProperties. +# @caches: the list of `SmpCacheProperties`. # # Since 9.2 ## diff --git a/qapi/machine.json b/qapi/machine.json index 2364893cba..f9bfda2151 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -188,7 +188,7 @@ # @acpi: machine type supports ACPI (since 8.0) # # @compat-props: The machine type's compatibility properties. Only -# present when query-machines argument @compat-props is true. +# present when `query-machines` argument @compat-props is true. # (since 9.1) # # Features: @@ -377,7 +377,7 @@ # # Wake up guest from suspend. If the guest has wake-up from suspend # support enabled (wakeup-suspend-support flag from -# query-current-machine), wake-up guest from suspend if the guest is +# `query-current-machine`), wake-up guest from suspend if the guest is # in SUSPENDED state. Return an error otherwise. # # Since: 1.1 @@ -589,7 +589,7 @@ # # List of CXL Fixed Memory Windows. # -# @cxl-fmw: List of CXLFixedMemoryWindowOptions +# @cxl-fmw: List of `CXLFixedMemoryWindowOptions` # # Since: 7.1 ## @@ -644,10 +644,10 @@ ## # @NumaCpuOptions: # -# Option "-numa cpu" overrides default cpu to node mapping. It -# accepts the same set of cpu properties as returned by -# query-hotpluggable-cpus[].props, where node-id could be used to -# override default node mapping. +# Option "-numa cpu" overrides default cpu to node mapping. It accepts +# the same set of cpu properties as returned by +# `query-hotpluggable-cpus[].props `, where +# node-id could be used to override default node mapping. # # Since: 2.10 ## @@ -661,7 +661,7 @@ # The memory hierarchy in the System Locality Latency and Bandwidth # Information Structure of HMAT (Heterogeneous Memory Attribute Table) # -# For more information about @HmatLBMemoryHierarchy, see chapter +# For more information about `HmatLBMemoryHierarchy`, see chapter # 5.2.27.4: Table 5-146: Field "Flags" of ACPI 6.3 spec. # # @memory: the structure represents the memory performance @@ -683,7 +683,7 @@ # Data type in the System Locality Latency and Bandwidth Information # Structure of HMAT (Heterogeneous Memory Attribute Table) # -# For more information about @HmatLBDataType, see chapter 5.2.27.4: +# For more information about `HmatLBDataType`, see chapter 5.2.27.4: # Table 5-146: Field "Data Type" of ACPI 6.3 spec. # # @access-latency: access latency (nanoseconds) @@ -710,7 +710,7 @@ # Set the system locality latency and bandwidth information between # Initiator and Target proximity Domains. # -# For more information about @NumaHmatLBOptions, see chapter 5.2.27.4: +# For more information about `NumaHmatLBOptions`, see chapter 5.2.27.4: # Table 5-146 of ACPI 6.3 spec. # # @initiator: the Initiator Proximity Domain. @@ -746,7 +746,7 @@ # Cache associativity in the Memory Side Cache Information Structure # of HMAT # -# For more information of @HmatCacheAssociativity, see chapter +# For more information of `HmatCacheAssociativity`, see chapter # 5.2.27.5: Table 5-147 of ACPI 6.3 spec. # # @none: None (no memory side cache in this proximity domain, or cache @@ -767,7 +767,7 @@ # Cache write policy in the Memory Side Cache Information Structure of # HMAT # -# For more information of @HmatCacheWritePolicy, see chapter 5.2.27.5: +# For more information of `HmatCacheWritePolicy`, see chapter 5.2.27.5: # Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec. # # @none: None (no memory side cache in this proximity domain, or cache @@ -787,7 +787,7 @@ # # Set the memory side cache information for a given memory domain. # -# For more information of @NumaHmatCacheOptions, see chapter 5.2.27.5: +# For more information of `NumaHmatCacheOptions`, see chapter 5.2.27.5: # Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec. # # @node-id: the memory proximity domain to which the memory belongs. @@ -964,7 +964,7 @@ # # The ids other than the node-id specify the position of the CPU # within the CPU topology (as defined by the machine property "smp", -# thus see also type @SMPConfiguration) +# thus see also type `SMPConfiguration`) # # @node-id: NUMA node ID the CPU belongs to # @@ -992,7 +992,7 @@ # Since: 2.7 ## { 'struct': 'CpuInstanceProperties', - # Keep these in sync with the properties device_add accepts + # Keep these in sync with the properties `device_add` accepts 'data': { '*node-id': 'int', '*drawer-id': 'int', '*book-id': 'int', @@ -1008,19 +1008,19 @@ ## # @HotpluggableCPU: # -# @type: CPU object type for usage with device_add command +# @type: CPU object type for usage with `device_add` command # # @props: list of properties to pass for hotplugging a CPU with -# device_add +# `device_add` # -# @vcpus-count: number of logical VCPU threads @HotpluggableCPU +# @vcpus-count: number of logical VCPU threads `HotpluggableCPU` # provides # # @qom-path: link to existing CPU object if CPU is present or omitted # if CPU is not present. # # .. note:: Management should be prepared to pass through additional -# properties with device_add. +# properties with `device_add`. # # Since: 2.7 ## @@ -1179,7 +1179,7 @@ # @BALLOON_CHANGE: # # Emitted when the guest changes the actual BALLOON level. This value -# is equivalent to the @actual field return by the 'query-balloon' +# is equivalent to the @actual field return by the `query-balloon` # command # # @actual: the logical size of the VM in bytes. Formula used: @@ -1965,7 +1965,7 @@ # # The result of a CPU model baseline. # -# @model: the baselined CpuModelInfo. +# @model: the baselined `CpuModelInfo`. # # Since: 2.8 ## @@ -2014,28 +2014,28 @@ # # * QEMU version: CPU models may look different depending on the QEMU # version. (Except for CPU models reported as "static" in -# query-cpu-definitions.) +# `query-cpu-definitions`.) # * machine-type: CPU model may look different depending on the # machine-type. (Except for CPU models reported as "static" in -# query-cpu-definitions.) +# `query-cpu-definitions`.) # * machine options (including accelerator): in some architectures, # CPU models may look different depending on machine and accelerator # options. (Except for CPU models reported as "static" in -# query-cpu-definitions.) +# `query-cpu-definitions`.) # * "-cpu" arguments and global properties: arguments to the -cpu # option and global properties may affect expansion of CPU models. -# Using query-cpu-model-expansion while using these is not advised. +# Using `query-cpu-model-expansion` while using these is not advised. # # Some architectures may not support comparing CPU models. s390x # supports comparing CPU models. # # @modela: description of the first CPU model to compare, referred to -# as "model A" in CpuModelCompareResult +# as "model A" in `CpuModelCompareResult` # # @modelb: description of the second CPU model to compare, referred to -# as "model B" in CpuModelCompareResult +# as "model B" in `CpuModelCompareResult` # -# Returns: a CpuModelCompareInfo describing how both CPU models +# Returns: a `CpuModelCompareInfo` describing how both CPU models # compare # # Errors: @@ -2068,17 +2068,17 @@ # # * QEMU version: CPU models may look different depending on the QEMU # version. (Except for CPU models reported as "static" in -# query-cpu-definitions.) +# `query-cpu-definitions`.) # * machine-type: CPU model may look different depending on the # machine-type. (Except for CPU models reported as "static" in -# query-cpu-definitions.) +# `query-cpu-definitions`.) # * machine options (including accelerator): in some architectures, # CPU models may look different depending on machine and accelerator # options. (Except for CPU models reported as "static" in -# query-cpu-definitions.) +# `query-cpu-definitions`.) # * "-cpu" arguments and global properties: arguments to the -cpu # option and global properties may affect expansion of CPU models. -# Using query-cpu-model-expansion while using these is not advised. +# Using `query-cpu-model-expansion` while using these is not advised. # # Some architectures may not support baselining CPU models. s390x # supports baselining CPU models. @@ -2087,7 +2087,7 @@ # # @modelb: description of the second CPU model to baseline # -# Returns: a CpuModelBaselineInfo describing the baselined CPU model +# Returns: a `CpuModelBaselineInfo` describing the baselined CPU model # # Errors: # - if baselining CPU models is not supported by the target @@ -2107,7 +2107,7 @@ # # The result of a cpu model expansion. # -# @model: the expanded CpuModelInfo. +# @model: the expanded `CpuModelInfo`. # # @deprecated-props: an optional list of properties that are flagged as # deprecated by the CPU vendor. The list depends on the @@ -2136,17 +2136,17 @@ # # * QEMU version: CPU models may look different depending on the QEMU # version. (Except for CPU models reported as "static" in -# query-cpu-definitions.) +# `query-cpu-definitions`.) # * machine-type: CPU model may look different depending on the # machine-type. (Except for CPU models reported as "static" in -# query-cpu-definitions.) +# `query-cpu-definitions`.) # * machine options (including accelerator): in some architectures, # CPU models may look different depending on machine and accelerator # options. (Except for CPU models reported as "static" in -# query-cpu-definitions.) +# `query-cpu-definitions`.) # * "-cpu" arguments and global properties: arguments to the -cpu # option and global properties may affect expansion of CPU models. -# Using query-cpu-model-expansion while using these is not advised. +# Using `query-cpu-model-expansion` while using these is not advised. # # Some architectures may not support all expansion types. s390x # supports "full" and "static". Arm only supports "full". @@ -2155,7 +2155,7 @@ # # @type: expansion type, specifying how to expand the CPU model # -# Returns: a CpuModelExpansionInfo describing the expanded CPU model +# Returns: a `CpuModelExpansionInfo` describing the expanded CPU model # # Errors: # - if expanding CPU models is not supported @@ -2194,7 +2194,7 @@ # from running in the current host. (since 2.8) # # @typename: Type name that can be used as argument to -# @device-list-properties, to introspect properties configurable +# `device-list-properties`, to introspect properties configurable # using -cpu or -global. (since 2.9) # # @alias-of: Name of CPU model this model is an alias for. The target From b51ea1c42111464961a4b2bb3f1d3f4f0ddfc006 Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:39:55 -0400 Subject: [PATCH 19/29] qapi: add cross-references to migration.json Note that a reference to MIGRATION needs to be disambiguated with a :qapi:event: prefix. Without this, Sphinx complains more than one target found for 'any' cross-reference 'MIGRATION': could be :std:ref:`Migration framework` or :qapi:event:`QMP:migration.MIGRATION` Signed-off-by: John Snow Message-ID: <20250711054005.60969-9-jsnow@redhat.com> Reviewed-by: Markus Armbruster [Commit message amended to explain need for :qapi:event:] Signed-off-by: Markus Armbruster --- qapi/migration.json | 68 ++++++++++++++++++++++----------------------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/qapi/migration.json b/qapi/migration.json index 57653160eb..e08a99bb82 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -195,14 +195,14 @@ # # Information about current migration process. # -# @status: @MigrationStatus describing the current migration status. +# @status: `MigrationStatus` describing the current migration status. # If this field is not returned, no migration process has been # initiated # -# @ram: @MigrationStats containing detailed migration status, only +# @ram: `MigrationStats` containing detailed migration status, only # returned if status is 'active' or 'completed'(since 1.2) # -# @xbzrle-cache: @XBZRLECacheStats containing detailed XBZRLE +# @xbzrle-cache: `XBZRLECacheStats` containing detailed XBZRLE # migration statistics, only returned if XBZRLE feature is on and # status is 'active' or 'completed' (since 1.2) # @@ -266,7 +266,7 @@ # @socket-address: Only used for tcp, to know what the real port is # (Since 4.0) # -# @vfio: @VfioStats containing detailed VFIO devices migration +# @vfio: `VfioStats` containing detailed VFIO devices migration # statistics, only returned if VFIO device is present, migration # is supported by all VFIO devices and status is 'active' or # 'completed' (since 5.2) @@ -277,7 +277,7 @@ # # @dirty-limit-throttle-time-per-round: Maximum throttle time (in # microseconds) of virtual CPUs each dirty ring full round, which -# shows how MigrationCapability dirty-limit affects the guest +# shows how `MigrationCapability` dirty-limit affects the guest # during live migration. (Since 8.1) # # @dirty-limit-ring-full-time: Estimated average dirty ring full time @@ -627,7 +627,7 @@ # # @normal: the original form of migration. (since 8.2) # -# @cpr-reboot: The migrate command stops the VM and saves state to the +# @cpr-reboot: The `migrate` command stops the VM and saves state to the # URI. After quitting QEMU, the user resumes by running QEMU # -incoming. # @@ -677,7 +677,7 @@ # # New QEMU reads the CPR channel before opening a monitor, hence # the CPR channel cannot be specified in the list of channels for -# a migrate-incoming command. It may only be specified on the +# a `migrate-incoming` command. It may only be specified on the # command line. # # The main channel address cannot be a file type, and for an @@ -688,10 +688,10 @@ # memory-backend-epc is not supported. The VM must be started # with the '-machine aux-ram-share=on' option. # -# When using -incoming defer, you must issue the migrate command +# When using -incoming defer, you must issue the `migrate` command # to old QEMU before issuing any monitor commands to new QEMU. # However, new QEMU does not open and read the migration stream -# until you issue the migrate incoming command. +# until you issue the `migrate-incoming` command. # # (since 10.0) ## @@ -913,11 +913,11 @@ # @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. # Defaults to 1. (Since 8.1) # -# @mode: Migration mode. See description in @MigMode. Default is +# @mode: Migration mode. See description in `MigMode`. Default is # 'normal'. (Since 8.2) # # @zero-page-detection: Whether and how to detect zero pages. -# See description in @ZeroPageDetection. Default is 'multifd'. +# See description in `ZeroPageDetection`. Default is 'multifd'. # (since 9.0) # # @direct-io: Open migration files with O_DIRECT when possible. This @@ -1094,11 +1094,11 @@ # @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. # Defaults to 1. (Since 8.1) # -# @mode: Migration mode. See description in @MigMode. Default is +# @mode: Migration mode. See description in `MigMode`. Default is # 'normal'. (Since 8.2) # # @zero-page-detection: Whether and how to detect zero pages. -# See description in @ZeroPageDetection. Default is 'multifd'. +# See description in `ZeroPageDetection`. Default is 'multifd'. # (since 9.0) # # @direct-io: Open migration files with O_DIRECT when possible. This @@ -1110,8 +1110,8 @@ # @unstable: Members @x-checkpoint-delay and # @x-vcpu-dirty-limit-period are experimental. # -# TODO: either fuse back into MigrationParameters, or make -# MigrationParameters members mandatory +# TODO: either fuse back into `MigrationParameters`, or make +# `MigrationParameters` members mandatory # # Since: 2.4 ## @@ -1304,11 +1304,11 @@ # @vcpu-dirty-limit: Dirtyrate limit (MB/s) during live migration. # Defaults to 1. (Since 8.1) # -# @mode: Migration mode. See description in @MigMode. Default is +# @mode: Migration mode. See description in `MigMode`. Default is # 'normal'. (Since 8.2) # # @zero-page-detection: Whether and how to detect zero pages. -# See description in @ZeroPageDetection. Default is 'multifd'. +# See description in `ZeroPageDetection`. Default is 'multifd'. # (since 9.0) # # @direct-io: Open migration files with O_DIRECT when possible. This @@ -1398,7 +1398,7 @@ # # Emitted when a migration event happens # -# @status: @MigrationStatus describing the current migration status. +# @status: `MigrationStatus` describing the current migration status. # # Since: 2.4 # @@ -1519,8 +1519,8 @@ # The reason for a COLO exit. # # @none: failover has never happened. This state does not occur in -# the COLO_EXIT event, and is only visible in the result of -# query-colo-status. +# the `COLO_EXIT` event, and is only visible in the result of +# `query-colo-status`. # # @request: COLO exit is due to an external request. # @@ -1775,8 +1775,8 @@ # list connected to a destination interface endpoint. # # @exit-on-error: Exit on incoming migration failure. Default true. -# When set to false, the failure triggers a MIGRATION event, and -# error details could be retrieved with query-migrate. +# When set to false, the failure triggers a :qapi:event:`MIGRATION` +# event, and error details could be retrieved with `query-migrate`. # (since 9.1) # # Since: 2.3 @@ -1788,7 +1788,7 @@ # already exposed above libvirt. # # 2. QEMU must be started with -incoming defer to allow -# migrate-incoming to be used. +# `migrate-incoming` to be used. # # 3. The uri format is the same as for -incoming # @@ -1841,7 +1841,7 @@ # devices of the VM are not saved by this command. # # @filename: the file to save the state of the devices to as binary -# data. See xen-save-devices-state.txt for a description of the +# data. See `xen-save-devices-state`.txt for a description of the # binary format. # # @live: Optional argument to ask QEMU to treat this command as part @@ -1882,7 +1882,7 @@ # devices of the VM are not loaded by this command. # # @filename: the file to load the state of the devices from as binary -# data. See xen-save-devices-state.txt for a description of the +# data. See `xen-save-devices-state`.txt for a description of the # binary format. # # Since: 2.7 @@ -1922,7 +1922,7 @@ ## # @ReplicationStatus: # -# The result format for 'query-xen-replication-status'. +# The result format for `query-xen-replication-status`. # # @error: true if an error happened, false if replication is normal. # @@ -1971,7 +1971,7 @@ ## # @COLOStatus: # -# The result format for 'query-colo-status'. +# The result format for `query-colo-status`. # # @mode: COLO running mode. If COLO is running, this field will # return 'primary' or 'secondary'. @@ -2095,7 +2095,7 @@ # @DirtyRateMeasureMode: # # Method used to measure dirty page rate. Differences between -# available methods are explained in @calc-dirty-rate. +# available methods are explained in `calc-dirty-rate`. # # @page-sampling: use page sampling # @@ -2163,7 +2163,7 @@ # @calc-dirty-rate: # # Start measuring dirty page rate of the VM. Results can be retrieved -# with @query-dirty-rate after measurements are completed. +# with `query-dirty-rate` after measurements are completed. # # Dirty page rate is the number of pages changed in a given time # period expressed in MiB/s. The following methods of calculation are @@ -2236,7 +2236,7 @@ ## # @query-dirty-rate: # -# Query results of the most recent invocation of @calc-dirty-rate. +# Query results of the most recent invocation of `calc-dirty-rate`. # # @calc-time-unit: time unit in which to report calculation time. # By default it is reported in seconds. (Since 8.2) @@ -2286,7 +2286,7 @@ # # Requires KVM with accelerator property "dirty-ring-size" set. A # virtual CPU's dirty page rate is a measure of its memory load. To -# observe dirty page rates, use @calc-dirty-rate. +# observe dirty page rates, use `calc-dirty-rate`. # # @cpu-index: index of a virtual CPU, default is all. # @@ -2311,8 +2311,8 @@ # Cancel the upper limit of dirty page rate for virtual CPUs. # # Cancel the dirty page limit for the vCPU which has been set with -# set-vcpu-dirty-limit command. Note that this command requires -# support from dirty ring, same as the "set-vcpu-dirty-limit". +# `set-vcpu-dirty-limit` command. Note that this command requires +# support from dirty ring, same as the `set-vcpu-dirty-limit`. # # @cpu-index: index of a virtual CPU, default is all. # @@ -2469,7 +2469,7 @@ # time it takes to load the snapshot. # # It is strongly recommended that @devices contain all writable block -# device nodes that can have changed since the original @snapshot-save +# device nodes that can have changed since the original `snapshot-save` # command execution. # # .. qmp-example:: From 4411a50e31157a1ee81147c2a6d6f1372a7bf6e8 Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:39:56 -0400 Subject: [PATCH 20/29] qapi: add cross-references to net.json Signed-off-by: John Snow Message-ID: <20250711054005.60969-10-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/net.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/qapi/net.json b/qapi/net.json index a266c6786e..1dda21fe61 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -657,7 +657,7 @@ # this to zero disables this function. This member is mutually # exclusive with @reconnect. (default: 0) (Since: 9.2) # -# Only SocketAddress types 'unix', 'inet' and 'fd' are supported. +# Only `SocketAddress` types 'unix', 'inet' and 'fd' are supported. # # Features: # @@ -682,7 +682,7 @@ # # @local: local address # -# Only SocketAddress types 'unix', 'inet' and 'fd' are supported. +# Only `SocketAddress` types 'unix', 'inet' and 'fd' are supported. # # If remote address is present and it's a multicast address, local # address is optional. Otherwise local address is required and remote @@ -892,7 +892,7 @@ ## # @NIC_RX_FILTER_CHANGED: # -# Emitted once until the 'query-rx-filter' command is executed, the +# Emitted once until the `query-rx-filter` command is executed, the # first event will always be emitted # # @name: net client name From b9abf7dd3f926e50029bd450e2d9c7cd2f1dde51 Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:39:57 -0400 Subject: [PATCH 21/29] qapi: add cross-references to pci.json Signed-off-by: John Snow Message-ID: <20250711054005.60969-11-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/pci.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qapi/pci.json b/qapi/pci.json index 418ea4fc93..694c741e42 100644 --- a/qapi/pci.json +++ b/qapi/pci.json @@ -85,7 +85,7 @@ # # @bus: information about the bus the device resides on # -# @devices: a list of @PciDeviceInfo for each device on this bridge +# @devices: a list of `PciDeviceInfo` for each device on this bridge # # Since: 0.14 ## From 91581b49e1d1910c1e5af641e7b8afa95c1b0a53 Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:39:58 -0400 Subject: [PATCH 22/29] qapi: add cross-references to QOM Signed-off-by: John Snow Message-ID: <20250711054005.60969-12-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/qdev.json | 4 ++-- qapi/qom.json | 13 +++++++------ 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/qapi/qdev.json b/qapi/qdev.json index 6441357e00..e14a0c9259 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -97,10 +97,10 @@ # from the guest. Hot removal is an operation that requires guest # cooperation. This command merely requests that the guest begin # the hot removal process. Completion of the device removal -# process is signaled with a DEVICE_DELETED event. Guest reset +# process is signaled with a `DEVICE_DELETED` event. Guest reset # will automatically complete removal for all devices. If a # guest-side error in the hot removal process is detected, the -# device will not be removed and a DEVICE_UNPLUG_GUEST_ERROR event +# device will not be removed and a `DEVICE_UNPLUG_GUEST_ERROR` event # is sent. Some errors cannot be detected. # # Since: 0.14 diff --git a/qapi/qom.json b/qapi/qom.json index aa09eddbf9..4e85baae47 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -52,7 +52,7 @@ # # List properties of a object given a path in the object model. # -# @path: the path within the object model. See @qom-get for a +# @path: the path within the object model. See `qom-get` for a # description of this parameter. # # Returns: a list that describe the properties of the object. @@ -129,12 +129,12 @@ # # Set a property value. # -# @path: see @qom-get for a description of this parameter +# @path: see `qom-get` for a description of this parameter # # @property: the property name to set # # @value: a value who's type is appropriate for the property type. -# See @qom-get for a description of type mapping. +# See `qom-get` for a description of type mapping. # # Since: 1.2 # @@ -153,7 +153,7 @@ ## # @ObjectTypeInfo: # -# This structure describes a search result from @qom-list-types +# This structure describes a search result from `qom-list-types` # # @name: the type name found in the search # @@ -193,6 +193,7 @@ # # @typename: 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. @@ -787,7 +788,7 @@ # # Properties for x-remote-object objects. # -# @fd: file descriptor name previously passed via 'getfd' command +# @fd: file descriptor name previously passed via `getfd` command # # @devid: the id of the device to be associated with the file # descriptor @@ -816,7 +817,7 @@ # # Properties for iommufd objects. # -# @fd: file descriptor name previously passed via 'getfd' command, +# @fd: file descriptor name previously passed via `getfd` command, # which represents a pre-opened /dev/iommu. This allows the # iommufd object to be shared across several subsystems (VFIO, # VDPA, ...), and the file descriptor to be shared with other From 551c00b8fac1f0532ba10bac05a5da7b7b508f71 Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:39:59 -0400 Subject: [PATCH 23/29] qapi: add cross-references to replay.json Signed-off-by: John Snow Message-ID: <20250711054005.60969-13-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/replay.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/qapi/replay.json b/qapi/replay.json index e46c5c1d3f..ccf84da68e 100644 --- a/qapi/replay.json +++ b/qapi/replay.json @@ -49,8 +49,8 @@ # @query-replay: # # Retrieve the record/replay information. It includes current -# instruction count which may be used for @replay-break and -# @replay-seek commands. +# instruction count which may be used for `replay-break` and +# `replay-seek` commands. # # Returns: record/replay information. # @@ -72,7 +72,7 @@ # breakpoint. When breakpoint is set, any prior one is removed. The # breakpoint may be set only in replay mode and only "in the future", # i.e. at instruction counts greater than the current one. The -# current instruction count can be observed with @query-replay. +# current instruction count can be observed with `query-replay`. # # @icount: instruction count to stop at # @@ -88,7 +88,7 @@ ## # @replay-delete-break: # -# Remove replay breakpoint which was set with @replay-break. The +# Remove replay breakpoint which was set with `replay-break`. The # command is ignored when there are no replay breakpoints. # # Since: 5.2 @@ -108,7 +108,7 @@ # snapshot and replays the execution to find the desired instruction. # When there is no preceding snapshot or the execution is not # replayed, then the command fails. Instruction count can be obtained -# with the @query-replay command. +# with the `query-replay` command. # # @icount: target instruction count # From 57d2ad7d2f534d510c7afb44d574d6313a0ab91e Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:40:00 -0400 Subject: [PATCH 24/29] qapi: add cross-references to run-state.json Signed-off-by: John Snow Message-ID: <20250711054005.60969-14-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/run-state.json | 46 ++++++++++++++++++++++----------------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/qapi/run-state.json b/qapi/run-state.json index 76f14569ff..54ba5c9a3f 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -70,9 +70,9 @@ # # @host-error: An error prevents further use of guest # -# @host-qmp-quit: Reaction to the QMP command 'quit' +# @host-qmp-quit: Reaction to the QMP command `quit` # -# @host-qmp-system-reset: Reaction to the QMP command 'system_reset' +# @host-qmp-system-reset: Reaction to the QMP command `system_reset` # # @host-signal: Reaction to a signal, such as SIGINT # @@ -108,7 +108,7 @@ # # @running: true if all VCPUs are runnable, false if not runnable # -# @status: the virtual machine @RunState +# @status: the virtual machine `RunState` # # Since: 0.14 ## @@ -143,12 +143,12 @@ # hardware-specific action) rather than a host request (such as # sending QEMU a SIGINT). (since 2.10) # -# @reason: The @ShutdownCause which resulted in the SHUTDOWN. +# @reason: The `ShutdownCause` which resulted in the `SHUTDOWN`. # (since 4.0) # # .. note:: If the command-line option ``-no-shutdown`` has been -# specified, QEMU will not exit, and a STOP event will eventually -# follow the SHUTDOWN event. +# specified, QEMU will not exit, and a `STOP` event will eventually +# follow the `SHUTDOWN` event. # # Since: 0.12 # @@ -183,9 +183,9 @@ # @guest: If true, the reset was triggered by a guest request (such as # a guest-initiated ACPI reboot request or other hardware-specific # action) rather than a host request (such as the QMP command -# system_reset). (since 2.10) +# `system_reset`). (since 2.10) # -# @reason: The @ShutdownCause of the RESET. (since 4.0) +# @reason: The `ShutdownCause` of the `RESET`. (since 4.0) # # Since: 0.12 # @@ -247,7 +247,7 @@ # saved on disk, for example, S4 state, which is sometimes called # hibernate state # -# .. note:: QEMU shuts down (similar to event @SHUTDOWN) when entering +# .. note:: QEMU shuts down (similar to event `SHUTDOWN`) when entering # this state. # # Since: 1.2 @@ -281,8 +281,8 @@ # # @action: action that has been taken # -# .. note:: If action is "reset", "shutdown", or "pause" the WATCHDOG -# event is followed respectively by the RESET, SHUTDOWN, or STOP +# .. note:: If action is "reset", "shutdown", or "pause" the `WATCHDOG` +# event is followed respectively by the `RESET`, `SHUTDOWN`, or `STOP` # events. # # .. note:: This event is rate-limited. @@ -378,7 +378,7 @@ # # Set watchdog action. # -# @action: @WatchdogAction action taken when watchdog timer expires. +# @action: `WatchdogAction` action taken when watchdog timer expires. # # Since: 2.11 # @@ -396,13 +396,13 @@ # Set the actions that will be taken by the emulator in response to # guest events. # -# @reboot: @RebootAction action taken on guest reboot. +# @reboot: `RebootAction` action taken on guest reboot. # -# @shutdown: @ShutdownAction action taken on guest shutdown. +# @shutdown: `ShutdownAction` action taken on guest shutdown. # -# @panic: @PanicAction action taken on guest panic. +# @panic: `PanicAction` action taken on guest panic. # -# @watchdog: @WatchdogAction action taken when watchdog timer expires. +# @watchdog: `WatchdogAction` action taken when watchdog timer expires. # # Since: 6.0 # @@ -529,20 +529,20 @@ # # Hyper-V specific guest panic information (HV crash MSRs) # -# @arg1: for Windows, STOP code for the guest crash. For Linux, +# @arg1: for Windows, `STOP` code for the guest crash. For Linux, # an error code. # -# @arg2: for Windows, first argument of the STOP. For Linux, the +# @arg2: for Windows, first argument of the `STOP`. For Linux, the # guest OS ID, which has the kernel version in bits 16-47 and # 0x8100 in bits 48-63. # -# @arg3: for Windows, second argument of the STOP. For Linux, the +# @arg3: for Windows, second argument of the `STOP`. For Linux, the # program counter of the guest. # -# @arg4: for Windows, third argument of the STOP. For Linux, the +# @arg4: for Windows, third argument of the `STOP`. For Linux, the # RAX register (x86) or the stack pointer (aarch64) of the guest. # -# @arg5: for Windows, fourth argument of the STOP. For x86 Linux, the +# @arg5: for Windows, fourth argument of the `STOP`. For x86 Linux, the # stack pointer of the guest. # # Since: 2.9 @@ -630,11 +630,11 @@ # # Emitted when a memory failure occurs on host side. # -# @recipient: recipient is defined as @MemoryFailureRecipient. +# @recipient: recipient is defined as `MemoryFailureRecipient`. # # @action: action that has been taken. # -# @flags: flags for MemoryFailureAction. +# @flags: flags for `MemoryFailureAction`. # # Since: 5.2 # From bfdfd96388fed2c23b2a42c32c5dd1a96d437c20 Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:40:01 -0400 Subject: [PATCH 25/29] qapi: add cross-references to sockets.json Signed-off-by: John Snow Reviewed-by: Eric Blake Message-ID: <20250711054005.60969-15-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/sockets.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/qapi/sockets.json b/qapi/sockets.json index b5f4a8fecd..82046b0b3a 100644 --- a/qapi/sockets.json +++ b/qapi/sockets.json @@ -211,14 +211,14 @@ 'unix': 'UnixSocketAddressWrapper', 'vsock': 'VsockSocketAddressWrapper', 'fd': 'FdSocketAddressWrapper' } } -# Note: This type is deprecated in favor of SocketAddress. The -# difference between SocketAddressLegacy and SocketAddress is that the +# Note: This type is deprecated in favor of `SocketAddress`. The +# difference between `SocketAddressLegacy` and `SocketAddress` is that the # latter has fewer ``{}`` on the wire. ## # @SocketAddressType: # -# Available SocketAddress types +# Available `SocketAddress` types # # @inet: Internet address # From 64ebc732e1a1bc3a76b7412eca9f0fc6b0c235d1 Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:40:02 -0400 Subject: [PATCH 26/29] qapi: add cross-references to ui.json Signed-off-by: John Snow Message-ID: <20250711054005.60969-16-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/ui.json | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/qapi/ui.json b/qapi/ui.json index b48266c458..c672cf10f9 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -41,7 +41,7 @@ ## # @SetPasswordOptions: # -# Options for set_password. +# Options for `set_password`. # # @protocol: # - 'vnc' to modify the VNC server password @@ -65,7 +65,7 @@ ## # @SetPasswordOptionsVnc: # -# Options for set_password specific to the VNC protocol. +# Options for `set_password` specific to the VNC protocol. # # @display: The id of the display where the password should be # changed. Defaults to the first. @@ -96,7 +96,7 @@ ## # @ExpirePasswordOptions: # -# General options for expire_password. +# General options for `expire_password`. # # @protocol: # - 'vnc' to modify the VNC server expiration @@ -126,7 +126,7 @@ ## # @ExpirePasswordOptionsVnc: # -# Options for expire_password specific to the VNC protocol. +# Options for `expire_password` specific to the VNC protocol. # # @display: The id of the display where the expiration should be # changed. Defaults to the first. @@ -185,7 +185,7 @@ # the head can only be specified in conjunction with the device # ID. (Since 2.12) # -# @format: image format for screendump. (default: ppm) (Since 7.1) +# @format: image format for `screendump`. (default: ppm) (Since 7.1) # # Since: 0.14 # @@ -313,7 +313,7 @@ # unknown if spice server doesn't provide this information. # (since: 1.1) # -# @channels: a list of @SpiceChannel for each active spice channel +# @channels: a list of `SpiceChannel` for each active spice channel # # Since: 0.14 ## @@ -563,7 +563,7 @@ # - 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL # auth # -# @clients: a list of @VncClientInfo of all currently connected +# @clients: a list of `VncClientInfo` of all currently connected # clients # # Since: 0.14 @@ -626,12 +626,12 @@ # # @id: vnc server name. # -# @server: A list of @VncBasincInfo describing all listening sockets. +# @server: A list of `VncBasicInfo` describing all listening sockets. # The list can be empty (in case the vnc server is disabled). It # also may have multiple entries: normal + websocket, possibly # also ipv4 + ipv6 in the future. # -# @clients: A list of @VncClientInfo of all currently connected +# @clients: A list of `VncClientInfo` of all currently connected # clients. The list can be empty, for obvious reasons. # # @auth: The current authentication type used by the non-websockets @@ -852,7 +852,7 @@ # # An enumeration of key name. # -# This is used by the @send-key command. +# This is used by the `send-key` command. # # @unmapped: since 2.0 # @@ -1023,10 +1023,10 @@ # # Send keys to guest. # -# @keys: An array of @KeyValue elements. All @KeyValues in this array -# are simultaneously sent to the guest. A @KeyValue.number value -# is sent directly to the guest, while @KeyValue.qcode must be a -# valid @QKeyCode value +# @keys: An array of `KeyValue` elements. All @KeyValues in this array +# are simultaneously sent to the guest. A `KeyValue`.number value +# is sent directly to the guest, while `KeyValue`.qcode must be a +# valid `QKeyCode` value # # @hold-time: time to delay key up events, milliseconds. Defaults to # 100 @@ -1263,7 +1263,7 @@ # @head: head to send event(s) to, in case the display device supports # multiple scanouts. # -# @events: List of InputEvent union. +# @events: List of `InputEvent` union. # # Since: 2.6 # @@ -1367,7 +1367,7 @@ # first available node on the host. # # @p2p: Whether to use peer-to-peer connections (accepted through -# @add_client). +# `add_client`). # # @audiodev: Use the specified DBus audiodev to export audio. # @@ -1526,7 +1526,7 @@ # # Display (user interface) options. # -# @type: Which DisplayType QEMU should use. +# @type: Which `DisplayType` QEMU should use. # # @full-screen: Start user interface in fullscreen mode # (default: off). From 6e202378d1533d87f77c73ffb22fbb784d08f545 Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:40:03 -0400 Subject: [PATCH 27/29] qapi: add cross-references to virtio.json Signed-off-by: John Snow Message-ID: <20250711054005.60969-17-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/virtio.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/qapi/virtio.json b/qapi/virtio.json index 2e23512085..b29c850eaf 100644 --- a/qapi/virtio.json +++ b/qapi/virtio.json @@ -137,7 +137,7 @@ # @num-vqs: VirtIODevice virtqueue count. This is the number of # active virtqueues being used by the VirtIODevice. # -# @status: VirtIODevice configuration status (VirtioDeviceStatus) +# @status: VirtIODevice configuration status (`VirtioDeviceStatus`) # # @isr: VirtIODevice ISR # @@ -579,7 +579,7 @@ # .. qmp-example:: # :annotated: # -# Get VirtQueueStatus for virtio-vsock (vhost-vsock running) +# Get `VirtQueueStatus` for virtio-vsock (vhost-vsock running) # :: # # -> { "execute": "x-query-virtio-queue-status", @@ -606,7 +606,7 @@ # .. qmp-example:: # :annotated: # -# Get VirtQueueStatus for virtio-serial (no vhost) +# Get `VirtQueueStatus` for virtio-serial (no vhost) # :: # # -> { "execute": "x-query-virtio-queue-status", @@ -818,7 +818,7 @@ # # @index: Index of the element in the queue # -# @descs: List of descriptors (VirtioRingDesc) +# @descs: List of descriptors (`VirtioRingDesc`) # # @avail: VRingAvail info # From 13f53cc902b7fa6d1864f7c13c3b3c755d1001a5 Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:40:04 -0400 Subject: [PATCH 28/29] qapi: add cross-references to yank.json Signed-off-by: John Snow Acked-by: Lukas Straub Message-ID: <20250711054005.60969-18-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/yank.json | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/qapi/yank.json b/qapi/yank.json index c14de5229e..f3cd5c15d6 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -11,7 +11,7 @@ ## # @YankInstanceType: # -# An enumeration of yank instance types. See @YankInstance for more +# An enumeration of yank instance types. See `YankInstance` for more # information. # # Since: 6.0 @@ -22,7 +22,7 @@ ## # @YankInstanceBlockNode: # -# Specifies which block graph node to yank. See @YankInstance for +# Specifies which block graph node to yank. See `YankInstance` for # more information. # # @node-name: the name of the block graph node @@ -35,7 +35,7 @@ ## # @YankInstanceChardev: # -# Specifies which character device to yank. See @YankInstance for +# Specifies which character device to yank. See `YankInstance` for # more information. # # @id: the chardev's ID @@ -48,7 +48,7 @@ ## # @YankInstance: # -# A yank instance can be yanked with the @yank qmp command to recover +# A yank instance can be yanked with the `yank` qmp command to recover # from a hanging QEMU. # # @type: yank instance type @@ -59,9 +59,9 @@ # nbd server without attempting to reconnect. # - socket chardev: Yanking it will shut down the connected socket. # - migration: Yanking it will shut down all migration connections. -# Unlike @migrate_cancel, it will not notify the migration process, +# Unlike `migrate_cancel`, it will not notify the migration process, # so migration will go into @failed state, instead of @cancelled -# state. @yank should be used to recover from hangs. +# state. `yank` should be used to recover from hangs. # # Since: 6.0 ## @@ -76,7 +76,7 @@ # @yank: # # Try to recover from hanging QEMU by yanking the specified instances. -# See @YankInstance for more information. +# See `YankInstance` for more information. # # @instances: the instances to be yanked # @@ -102,7 +102,7 @@ ## # @query-yank: # -# Query yank instances. See @YankInstance for more information. +# Query yank instances. See `YankInstance` for more information. # # TODO: This line is a hack to separate the example from the body # From 68c0156de2581b69e62b2f04b58a89bdc762e603 Mon Sep 17 00:00:00 2001 From: John Snow Date: Fri, 11 Jul 2025 01:40:05 -0400 Subject: [PATCH 29/29] qapi: add cross-references to misc modules These modules don't have specific maintainers, so they're lumped in together here as miscellaneous. Signed-off-by: John Snow Message-ID: <20250711054005.60969-19-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/control.json | 2 +- qapi/ebpf.json | 2 +- qapi/introspect.json | 24 ++++++++++++------------ qapi/misc-arm.json | 2 +- qapi/misc-i386.json | 2 +- qapi/misc.json | 12 ++++++------ qapi/stats.json | 8 ++++---- 7 files changed, 26 insertions(+), 26 deletions(-) diff --git a/qapi/control.json b/qapi/control.json index 931a860b30..9a5302193d 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -13,7 +13,7 @@ # # Enable QMP capabilities. # -# @enable: An optional list of QMPCapability values to enable. The +# @enable: An optional list of `QMPCapability` values to enable. The # client must not enable any capability that is not mentioned in # the QMP greeting message. If the field is not provided, it # means no QMP capabilities will be enabled. (since 2.12) diff --git a/qapi/ebpf.json b/qapi/ebpf.json index d45054e666..f0257955fa 100644 --- a/qapi/ebpf.json +++ b/qapi/ebpf.json @@ -34,7 +34,7 @@ ## # @EbpfProgramID: # -# The eBPF programs that can be gotten with request-ebpf. +# The eBPF programs that can be gotten with `request-ebpf`. # # @rss: Receive side scaling, technology that allows steering traffic # between queues by calculation hash. Users may set up diff --git a/qapi/introspect.json b/qapi/introspect.json index be8511b067..53100714a8 100644 --- a/qapi/introspect.json +++ b/qapi/introspect.json @@ -18,11 +18,11 @@ ## # @query-qmp-schema: # -# Command query-qmp-schema exposes the QMP wire ABI as an array of -# SchemaInfo. This lets QMP clients figure out what commands and +# Command `query-qmp-schema` exposes the QMP wire ABI as an array of +# `SchemaInfo`. This lets QMP clients figure out what commands and # events are available in this QEMU, and their parameters and results. # -# However, the SchemaInfo can't reflect all the rules and restrictions +# However, the `SchemaInfo` can't reflect all the rules and restrictions # that apply to QMP. It's interface introspection (figuring out # what's there), not interface specification. The specification is in # the QAPI schema. @@ -56,7 +56,7 @@ ## # @SchemaMetaType: # -# This is a @SchemaInfo's meta type, i.e. the kind of entity it +# This is a `SchemaInfo`'s meta type, i.e. the kind of entity it # describes. # # @builtin: a predefined type such as 'int' or 'bool'. @@ -82,7 +82,7 @@ ## # @SchemaInfo: # -# @name: the entity's name, inherited from @base. The SchemaInfo is +# @name: the entity's name, inherited from @base. The `SchemaInfo` is # always referenced by this name. Commands and events have the # name defined in the QAPI schema. Unlike command and event # names, type names are not part of the wire ABI. Consequently, @@ -113,7 +113,7 @@ ## # @SchemaInfoBuiltin: # -# Additional SchemaInfo members for meta-type 'builtin'. +# Additional `SchemaInfo` members for meta-type 'builtin'. # # @json-type: the JSON type used for this type on the wire. # @@ -154,7 +154,7 @@ ## # @SchemaInfoEnum: # -# Additional SchemaInfo members for meta-type 'enum'. +# Additional `SchemaInfo` members for meta-type 'enum'. # # @members: the enum type's members, in no particular order. # (since 6.2) @@ -194,7 +194,7 @@ ## # @SchemaInfoArray: # -# Additional SchemaInfo members for meta-type 'array'. +# Additional `SchemaInfo` members for meta-type 'array'. # # @element-type: the array type's element type. # @@ -208,7 +208,7 @@ ## # @SchemaInfoObject: # -# Additional SchemaInfo members for meta-type 'object'. +# Additional `SchemaInfo` members for meta-type 'object'. # # @members: the object type's (non-variant) members, in no particular # order. @@ -273,7 +273,7 @@ ## # @SchemaInfoAlternate: # -# Additional SchemaInfo members for meta-type 'alternate'. +# Additional `SchemaInfo` members for meta-type 'alternate'. # # @members: the alternate type's members, in no particular order. The # members' wire encoding is distinct, see @@ -301,7 +301,7 @@ ## # @SchemaInfoCommand: # -# Additional SchemaInfo members for meta-type 'command'. +# Additional `SchemaInfo` members for meta-type 'command'. # # @arg-type: the name of the object type that provides the command's # parameters. @@ -323,7 +323,7 @@ ## # @SchemaInfoEvent: # -# Additional SchemaInfo members for meta-type 'event'. +# Additional `SchemaInfo` members for meta-type 'event'. # # @arg-type: the name of the object type that provides the event's # parameters. diff --git a/qapi/misc-arm.json b/qapi/misc-arm.json index f9dd743b52..f921d740f1 100644 --- a/qapi/misc-arm.json +++ b/qapi/misc-arm.json @@ -30,7 +30,7 @@ ## # @query-gic-capabilities: # -# It will return a list of GICCapability objects that describe its +# It will return a list of `GICCapability` objects that describe its # capability bits. # # On non-ARM targets this command will report an error as the GIC diff --git a/qapi/misc-i386.json b/qapi/misc-i386.json index 282bd3627b..c8c91a241c 100644 --- a/qapi/misc-i386.json +++ b/qapi/misc-i386.json @@ -26,7 +26,7 @@ ## # @SevState: # -# An enumeration of SEV state information used during @query-sev. +# An enumeration of SEV state information used during `query-sev`. # # @uninit: The guest is uninitialized. # diff --git a/qapi/misc.json b/qapi/misc.json index 7dbc29dbd6..28c641fe2f 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -23,7 +23,7 @@ # "@dbus-display" or the name of a character device (e.g. from # -chardev id=XXXX) # -# @fdname: file descriptor name previously passed via 'getfd' command +# @fdname: file descriptor name previously passed via `getfd` command # # @skipauth: whether to skip authentication. Only applies to "vnc" # and "spice" protocols @@ -228,7 +228,7 @@ # Known limitations: # # * This command is stateless, this means that commands that depend -# on state information (such as getfd) might not work. +# on state information (such as `getfd`) might not work. # # * Commands that prompt the user for data don't currently work. # @@ -255,7 +255,7 @@ # .. note:: If @fdname already exists, the file descriptor assigned to # it will be closed and replaced by the received file descriptor. # -# The 'closefd' command can be used to explicitly close the file +# The `closefd` command can be used to explicitly close the file # descriptor when it is no longer needed. # # .. qmp-example:: @@ -282,7 +282,7 @@ # .. note:: If @fdname already exists, the file descriptor assigned to # it will be closed and replaced by the received file descriptor. # -# The 'closefd' command can be used to explicitly close the file +# The `closefd` command can be used to explicitly close the file # descriptor when it is no longer needed. # # .. qmp-example:: @@ -475,7 +475,7 @@ # # @name: parameter name # -# @type: parameter @CommandLineParameterType +# @type: parameter `CommandLineParameterType` # # @help: human readable text string, not suitable for parsing. # @@ -497,7 +497,7 @@ # # @option: option name # -# @parameters: an array of @CommandLineParameterInfo +# @parameters: an array of `CommandLineParameterInfo` # # Since: 1.5 ## diff --git a/qapi/stats.json b/qapi/stats.json index b63a7369dd..151ac43c48 100644 --- a/qapi/stats.json +++ b/qapi/stats.json @@ -89,7 +89,7 @@ # @StatsRequest: # # Indicates a set of statistics that should be returned by -# query-stats. +# `query-stats`. # # @provider: provider for which to return statistics. # @@ -114,7 +114,7 @@ ## # @StatsFilter: # -# The arguments to the query-stats command; specifies a target for +# The arguments to the `query-stats` command; specifies a target for # which to request statistics and optionally the required subset of # information for that target. # @@ -185,7 +185,7 @@ # Return runtime-collected statistics for objects such as the VM or # its vCPUs. # -# The arguments are a StatsFilter and specify the provider and objects +# The arguments are a `StatsFilter` and specify the provider and objects # to return statistics about. # # Returns: a list of statistics, one for each provider and object @@ -205,7 +205,7 @@ # # @name: name of the statistic; each element of the schema is uniquely # identified by a target, a provider (both available in -# @StatsSchema) and the name. +# `StatsSchema`) and the name. # # @type: kind of statistic. #