[PATCH 4/9] qapi: convert multi-paragraph intros (structs)

[John Snow <jsnow@redhat.com>]

This patch converts some slightly-non-trivial intros with more than
one paragraph, but doesn't create any new intro/details splits.

Review notes: Again, the Numa Hmat options have text that are prime
candidates for a ".. seealso::" admonition, but I was uncertain as to
whether this information was principally for developers or for
users. If it's for developers, it can stay in the intro where it will
be dropped when inlined. If it is for users, they should be moved into
the details region.

The remaining structs have an awful lot of text, but I was not
immediately sure of which information we wanted to preserve when
inlined or not; these structures tend to be written as if they are
describing a command, but they actually only define a set of
arguments.

Advice? Opinions?

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/machine.json | 17 ++++++++---------
 qapi/net.json     | 34 +++++++++++++++-------------------
 qapi/qom.json     | 18 +++++++++---------
 3 files changed, 32 insertions(+), 37 deletions(-)

diff --git a/qapi/machine.json b/qapi/machine.json
index 710b638b3bf..aaecd151407 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -657,12 +657,11 @@
 
 ##
 # @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.
+#     For more information about `NumaHmatLBOptions`, see chapter
+#     5.2.27.4: Table 5-146 of ACPI 6.3 spec.
 #
 # @initiator: the Initiator Proximity Domain.
 #
@@ -734,11 +733,11 @@
 
 ##
 # @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.
+#     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.
 #
diff --git a/qapi/net.json b/qapi/net.json
index 7aabd8b9260..50dc3137182 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -681,11 +681,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')
 #
@@ -712,11 +711,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
@@ -755,15 +753,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
@@ -800,10 +797,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 51af9485e6d..3de06488768 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -1033,16 +1033,16 @@
 
 ##
 # @SevSnpGuestProperties:
+#     Properties for sev-snp-guest objects.  Most of these are direct
+#     arguments for the KVM_SNP_* interfaces documented in the Linux
+#     kernel source under
+#     Documentation/arch/x86/amd-memory-encryption.rst, which are in
+#     turn closely coupled with the SNP_INIT/SNP_LAUNCH_* firmware
+#     commands documented in the SEV-SNP Firmware ABI Specification
+#     (Rev 0.9).
 #
-# Properties for sev-snp-guest objects.  Most of these are direct
-# arguments for the KVM_SNP_* interfaces documented in the Linux
-# kernel source under
-# Documentation/arch/x86/amd-memory-encryption.rst, which are in turn
-# closely coupled with the SNP_INIT/SNP_LAUNCH_* firmware commands
-# documented in the SEV-SNP Firmware ABI Specification (Rev 0.9).
-#
-# More usage information is also available in the QEMU source tree
-# under docs/amd-memory-encryption.
+#     More usage information is also available in the QEMU source tree
+#     under docs/amd-memory-encryption.
 #
 # @policy: the 'POLICY' parameter to the SNP_LAUNCH_START command, as
 #     defined in the SEV-SNP firmware ABI (default: 0x30000)
-- 
2.55.0