Commit 55ee0bd2f5 for qemu.org
commit 55ee0bd2f50f7ad52840ec8942fc128a3822f917
Author: John Snow <jsnow@redhat.com>
Date: Mon Sep 28 15:25:57 2026 -0400
qapi: split intro sections for inlinable structs
This patch splits the intro/details section for structs which are used
in an inlinable context; i.e. structs used either as arguments for a
command/event, or used as a branch of a union. The QAPI documentation
block for these entities will have their intro section left behind
when inlined into other contexts, but will still display the intro
section on standalone documentation for these types.
This patch does not change how the rendered documentation currently
looks, except:
1. MemoryBackendShmProperties and MemoryBackendEpcProperties see their
member descriptions move upwards to just below their formalized
introductory sections.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20260928192557.509157-11-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
diff --git a/qapi/block-export.json b/qapi/block-export.json
index 77459f6321..e3cee2fb5c 100644
--- a/qapi/block-export.json
+++ b/qapi/block-export.json
@@ -154,9 +154,8 @@
##
# @BlockExportOptionsFuse:
-#
-# Options for exporting a block graph node on some (file) mountpoint
-# as a raw image.
+# Options for exporting a block graph node on some (file)
+# mountpoint as a raw image.
#
# Multi-threading note: The FUSE export supports multi-threading.
# Currently, requests are distributed across these threads in a
diff --git a/qapi/crypto.json b/qapi/crypto.json
index 7b4c80edae..a8d753d360 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -429,8 +429,7 @@
##
# @SecretProperties:
-#
-# Properties for secret objects.
+# Properties for secret objects.
#
# Either @data or @file must be provided, but not both.
#
diff --git a/qapi/machine.json b/qapi/machine.json
index d09424b870..9b145c635b 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -690,9 +690,8 @@
##
# @NumaHmatLBOptions:
-#
-# Set the system locality latency and bandwidth information between
-# Initiator and Target proximity Domains.
+# 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: Table 5-146 of ACPI 6.3 spec.
@@ -766,8 +765,7 @@
##
# @NumaHmatCacheOptions:
-#
-# Set the memory side cache information for a given memory domain.
+# Set the memory side cache information for a given memory domain.
#
# For more information of `NumaHmatCacheOptions`, see chapter
# 5.2.27.5: Table 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
@@ -932,8 +930,7 @@
##
# @CpuInstanceProperties:
-#
-# Properties identifying a CPU.
+# Properties identifying a CPU.
#
# Which members are optional and which mandatory depends on the
# architecture and board.
diff --git a/qapi/net.json b/qapi/net.json
index 3541dd7cad..f0312dfb71 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -719,11 +719,10 @@
##
# @NetdevVhostVDPAOptions:
+# Vhost-vdpa network backend
#
-# Vhost-vdpa network backend
-#
-# vDPA device is a device that uses a datapath which complies with the
-# virtio specifications with a vendor specific control path.
+# vDPA device is a device that uses a datapath which complies with
+# the virtio specifications with a vendor specific control path.
#
# @vhostdev: path of vhost-vdpa device (default:'/dev/vhost-vdpa-0')
#
@@ -750,11 +749,10 @@
##
# @NetdevVmnetHostOptions:
+# vmnet (host mode) network backend.
#
-# vmnet (host mode) network backend.
-#
-# Allows the vmnet interface to communicate with other vmnet
-# interfaces that are in host mode and also with the host.
+# Allows the vmnet interface to communicate with other vmnet
+# interfaces that are in host mode and also with the host.
#
# @start-address: The starting IPv4 address to use for the interface.
# Must be in the private IP range (RFC 1918). Must be specified
@@ -793,15 +791,14 @@
##
# @NetdevVmnetSharedOptions:
+# vmnet (shared mode) network backend.
#
-# vmnet (shared mode) network backend.
-#
-# Allows traffic originating from the vmnet interface to reach the
-# Internet through a network address translator (NAT). The vmnet
-# interface can communicate with the host and with other shared mode
-# interfaces on the same subnet. If no DHCP settings, subnet mask and
-# IPv6 prefix specified, the interface can communicate with any of
-# other interfaces in shared mode.
+# Allows traffic originating from the vmnet interface to reach the
+# Internet through a network address translator (NAT). The vmnet
+# interface can communicate with the host and with other shared
+# mode interfaces on the same subnet. If no DHCP settings, subnet
+# mask and IPv6 prefix specified, the interface can communicate
+# with any of other interfaces in shared mode.
#
# @start-address: The starting IPv4 address to use for the interface.
# Must be in the private IP range (RFC 1918). Must be specified
@@ -838,10 +835,9 @@
##
# @NetdevVmnetBridgedOptions:
+# vmnet (bridged mode) network backend.
#
-# vmnet (bridged mode) network backend.
-#
-# Bridges the vmnet interface with a physical network interface.
+# Bridges the vmnet interface with a physical network interface.
#
# @ifname: The name of the physical interface to be bridged.
#
diff --git a/qapi/qom.json b/qapi/qom.json
index 59e523e3bf..e03ede3442 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -465,8 +465,7 @@
##
# @FilterRedirectorProperties:
-#
-# Properties for filter-redirector objects.
+# Properties for filter-redirector objects.
#
# At least one of @indev or @outdev must be present. If both are
# present, they must not refer to the same character device backend.
@@ -765,8 +764,7 @@
##
# @MemoryBackendShmProperties:
-#
-# Properties for memory-backend-shm objects.
+# Properties for memory-backend-shm objects.
#
# This memory backend supports only shared memory, which is the
# default.
@@ -780,8 +778,7 @@
##
# @MemoryBackendEpcProperties:
-#
-# Properties for memory-backend-epc objects.
+# Properties for memory-backend-epc objects.
#
# The @merge boolean option is false by default with epc
#