dddaf7aa9e
- vdpa-dev: Fix initialisation order to restore VDUSE compatibility - tcg: Allow top bit of SIMD_DATA_BITS to be set in simd_desc() - migration: fix-possible-int-overflow - target/m68k: Map FPU exceptions to FPSR register - qemu-options: Fix CXL Fixed Memory Window interleave-granularity typo - hvf: arm: Fix encodings for ID_AA64PFR1_EL1 and debug System registers - hw/intc/arm_gic: Fix handling of NS view of GICC_APR<n> - qio: Inherit follow_coroutine_ctx across TLS - target/riscv: Fix the element agnostic function problem - accel/tcg: Fix typo causing tb->page_addr[1] to not be recorded - tcg/loongarch64: Fix tcg_out_movi vs some pcrel pointers - migration: Fix file migration with fdset - ui/vnc: don't return an empty SASL mechlist to the client - target/arm: Fix FJCVTZS vs flush-to-zero - hw/ppc/e500: Prefer QOM cast - sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments - hw/ppc/e500: Remove unused "irqs" parameter - hw/ppc/e500: Add missing device tree properties to i2c controller node - hw/i386/amd_iommu: Don't leak memory in amdvi_update_iotlb() - hw/arm/mps2-tz.c: fix RX/TX interrupts order - target/i386: csv: Add support to migrate the incoming context for CSV3 guest - target/i386: csv: Add support to migrate the outgoing context for CSV3 guest - target/i386: csv: Add support to migrate the incoming page for CSV3 guest - target/i386: csv: Add support to migrate the outgoing page for CSV3 guest - linux-headers: update kernel headers to include CSV3 migration cmds - vfio: Only map shared region for CSV3 virtual machine - vga: Force full update for CSV3 guest - target/i386: csv: Load initial image to private memory for CSV3 guest - target/i386: csv: Do not register/unregister guest secure memory for CSV3 guest - target/i386: cpu: Populate CPUID 0x8000_001F when CSV3 is active - target/i386: csv: Add command to load vmcb to CSV3 guest memory - target/i386: csv: Add command to load data to CSV3 guest memory - target/i386: csv: Add command to initialize CSV3 context - target/i386: csv: Add CSV3 context - next-kbd: convert to use qemu_input_handler_register() - qemu/bswap: Undefine CPU_CONVERT() once done - exec/memop: Remove unused memop_big_endian() helper - hw/nvme: fix handling of over-committed queues - 9pfs: fix crash on 'Treaddir' request - hw/misc/psp: Pin the hugepage memory specified by mem2 during use for psp - hw/misc: support tkm use mem2 memory - hw/i386: add mem2 option for qemu - kvm: add support for guest physical bits - target/i386: add guest-phys-bits cpu property Signed-off-by: Jiabo Feng <fengjiabo1@huawei.com> (cherry picked from commit f45f35e88509a4ffa9f62332ee9601e9fe1f8d09)
157 lines
5.1 KiB
Diff
157 lines
5.1 KiB
Diff
From c7fe47e4aab35c1817c4c53f0025a741a9e2ad57 Mon Sep 17 00:00:00 2001
|
|
From: Markus Armbruster <armbru@redhat.com>
|
|
Date: Fri, 28 Jun 2024 13:27:56 +0200
|
|
Subject: [PATCH] sphinx/qapidoc: Fix to generate doc for explicit, unboxed
|
|
arguments
|
|
|
|
When a command's arguments are specified as an explicit type T,
|
|
generated documentation points to the members of T.
|
|
|
|
Example:
|
|
|
|
##
|
|
# @announce-self:
|
|
#
|
|
# Trigger generation of broadcast RARP frames to update network
|
|
[...]
|
|
##
|
|
{ 'command': 'announce-self', 'boxed': true,
|
|
'data' : 'AnnounceParameters'}
|
|
|
|
generates
|
|
|
|
"announce-self" (Command)
|
|
-------------------------
|
|
|
|
Trigger generation of broadcast RARP frames to update network
|
|
[...]
|
|
|
|
Arguments
|
|
~~~~~~~~~
|
|
|
|
The members of "AnnounceParameters"
|
|
|
|
Except when the command takes its arguments unboxed , i.e. it doesn't
|
|
have 'boxed': true, we generate *nothing*. A few commands have a
|
|
reference in their doc comment to compensate, but most don't.
|
|
|
|
Example:
|
|
|
|
##
|
|
# @blockdev-snapshot-sync:
|
|
#
|
|
# Takes a synchronous snapshot of a block device.
|
|
#
|
|
# For the arguments, see the documentation of BlockdevSnapshotSync.
|
|
[...]
|
|
##
|
|
{ 'command': 'blockdev-snapshot-sync',
|
|
'data': 'BlockdevSnapshotSync',
|
|
'allow-preconfig': true }
|
|
|
|
generates
|
|
|
|
"blockdev-snapshot-sync" (Command)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Takes a synchronous snapshot of a block device.
|
|
|
|
For the arguments, see the documentation of BlockdevSnapshotSync.
|
|
[...]
|
|
|
|
Same for event data.
|
|
|
|
Fix qapidoc.py to generate the reference regardless of boxing. Delete
|
|
now redundant references in the doc comments.
|
|
|
|
Fixes: 4078ee5469e5 (docs/sphinx: Add new qapi-doc Sphinx extension)
|
|
Cc: qemu-stable@nongnu.org
|
|
Signed-off-by: Markus Armbruster <armbru@redhat.com>
|
|
Message-ID: <20240628112756.794237-1-armbru@redhat.com>
|
|
Reviewed-by: John Snow <jsnow@redhat.com>
|
|
(cherry picked from commit e389929d19a543ea5b34d02553b355f9f1c03162)
|
|
Signed-off-by: zhujun2 <zhujun2_yewu@cmss.chinamobile.com>
|
|
---
|
|
docs/sphinx/qapidoc.py | 12 +++++-------
|
|
qapi/block-core.json | 7 -------
|
|
2 files changed, 5 insertions(+), 14 deletions(-)
|
|
|
|
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
|
|
index 658c288f8f..3d19853444 100644
|
|
--- a/docs/sphinx/qapidoc.py
|
|
+++ b/docs/sphinx/qapidoc.py
|
|
@@ -229,15 +229,15 @@ def _nodes_for_enum_values(self, doc):
|
|
section += dlnode
|
|
return [section]
|
|
|
|
- def _nodes_for_arguments(self, doc, boxed_arg_type):
|
|
+ def _nodes_for_arguments(self, doc, arg_type):
|
|
"""Return list of doctree nodes for the arguments section"""
|
|
- if boxed_arg_type:
|
|
+ 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('', boxed_arg_type.name)],
|
|
+ nodes.literal('', arg_type.name)],
|
|
None)
|
|
section += dlnode
|
|
return [section]
|
|
@@ -341,8 +341,7 @@ def visit_command(self, name, info, ifcond, features, arg_type,
|
|
allow_preconfig, coroutine):
|
|
doc = self._cur_doc
|
|
self._add_doc('Command',
|
|
- self._nodes_for_arguments(doc,
|
|
- arg_type if boxed else None)
|
|
+ self._nodes_for_arguments(doc, arg_type)
|
|
+ self._nodes_for_features(doc)
|
|
+ self._nodes_for_sections(doc)
|
|
+ self._nodes_for_if_section(ifcond))
|
|
@@ -350,8 +349,7 @@ def visit_command(self, name, info, ifcond, features, arg_type,
|
|
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 if boxed else None)
|
|
+ self._nodes_for_arguments(doc, arg_type)
|
|
+ self._nodes_for_features(doc)
|
|
+ self._nodes_for_sections(doc)
|
|
+ self._nodes_for_if_section(ifcond))
|
|
diff --git a/qapi/block-core.json b/qapi/block-core.json
|
|
index ded6f0f6d2..0fa184698a 100644
|
|
--- a/qapi/block-core.json
|
|
+++ b/qapi/block-core.json
|
|
@@ -1662,8 +1662,6 @@
|
|
#
|
|
# Takes a synchronous snapshot of a block device.
|
|
#
|
|
-# For the arguments, see the documentation of BlockdevSnapshotSync.
|
|
-#
|
|
# Returns:
|
|
# - nothing on success
|
|
# - If @device is not a valid block device, DeviceNotFound
|
|
@@ -1693,8 +1691,6 @@
|
|
# device, the block device changes to using 'overlay' as its new
|
|
# active image.
|
|
#
|
|
-# For the arguments, see the documentation of BlockdevSnapshot.
|
|
-#
|
|
# Features:
|
|
#
|
|
# @allow-write-only-overlay: If present, the check whether this
|
|
@@ -6037,9 +6033,6 @@
|
|
# string, or a snapshot with name already exists, the operation will
|
|
# fail.
|
|
#
|
|
-# For the arguments, see the documentation of
|
|
-# BlockdevSnapshotInternal.
|
|
-#
|
|
# Returns:
|
|
# - nothing on success
|
|
# - If @device is not a valid block device, GenericError
|
|
--
|
|
2.41.0.windows.1
|
|
|