[PATCH v2 0/8] qapi: convert intros for qga, firmware, etc

[PATCH v2 0/8] qapi: convert intros for qga, firmware, etc

[John Snow]

v2: minor changes (Markus)
    Dropped now irrelevant final patch (Oops)

John Snow (8):
  qapi: convert/split remaining qapi/qmp intro sections
  qapi: convert intro sections for unit tests
  qapi: convert trivial intros for qga/qapi-schema.json
  qapi: convert simple intros for qga/qapi-schema.json
  qapi: split intros at natural cutoff points for qga/qapi-schema.json
  qapi: split intros for qga/qapi-schema.json
  qapi: convert intro sections for docs/interop/firmware.json
  qapi: convert intro sections for docs/interop/vhost-user.json

 docs/interop/firmware.json                    |  76 +++---
 docs/interop/vhost-user.json                  |  27 +-
 qapi/block.json                               |   5 +-
 qapi/machine-s390x.json                       |   3 +-
 qapi/machine.json                             |   3 +-
 qapi/net.json                                 |  24 +-
 qga/qapi-schema.json                          | 249 +++++++-----------
 tests/qapi-schema/doc-good.json               |   8 +-
 tests/qapi-schema/doc-good.out                |  15 +-
 tests/qapi-schema/doc-interleaved-section.err |   2 +-
 .../qapi-schema/doc-interleaved-section.json  |   3 +-
 11 files changed, 161 insertions(+), 254 deletions(-)

-- 
2.55.0

[PATCH v2 1/8] qapi: convert/split remaining qapi/qmp intro sections

[John Snow]

A few slipped in during the mass conversion, get those too. Mostly
trivial conversion, with the exception of @x-qemu-io which introduces
a new split.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/block.json         |  5 +++--
 qapi/machine-s390x.json |  3 +--
 qapi/machine.json       |  3 +--
 qapi/net.json           | 24 ++++++++----------------
 4 files changed, 13 insertions(+), 22 deletions(-)

diff --git a/qapi/block.json b/qapi/block.json
index 13c47e1eb44..0a88d405a26 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -597,9 +597,10 @@
 
 ##
 # @x-qemu-io:
+#     Run a qemu-io command on a block device.
 #
-# Run a qemu-io command on a block device.  Take either a block
-# backend name or a qdev ID to identify the device.
+# Take either a block backend name or a qdev ID to identify the
+# device.
 #
 # @device: the block backend name, node-name to run the
 #     command on.
diff --git a/qapi/machine-s390x.json b/qapi/machine-s390x.json
index 670a1f9d926..8d8cbe2fb75 100644
--- a/qapi/machine-s390x.json
+++ b/qapi/machine-s390x.json
@@ -138,8 +138,7 @@
 
 ##
 # @BootCertificates:
-#
-# Boot certificates for secure IPL.
+#     Boot certificates for secure IPL.
 #
 # @path: path to an X.509 certificate file or a directory containing
 #      certificate files.
diff --git a/qapi/machine.json b/qapi/machine.json
index 1220116bf7d..6eb14c62851 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1390,8 +1390,7 @@
 
 ##
 # @SpMemDeviceInfo:
-#
-# sp-mem device state information
+#     sp-mem device state information
 #
 # @id: device's ID
 #
diff --git a/qapi/net.json b/qapi/net.json
index 2a186a71b93..f0312dfb714 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -1275,8 +1275,7 @@
 
 ##
 # @UsernetInfo:
-#
-# Information about a user-mode network stack (slirp).
+#     Information about a user-mode network stack (slirp).
 #
 # @hub-id: The hub id, if available.
 #
@@ -1295,8 +1294,7 @@
 
 ##
 # @x-query-usernet:
-#
-# Query user-mode network stack connection states.
+#     Query user-mode network stack connection states.
 #
 # Features:
 #
@@ -1319,8 +1317,7 @@
 
 ##
 # @NetFilterInfo:
-#
-# Information about a netfilter attached to a network client.
+#     Information about a netfilter attached to a network client.
 #
 # @name: filter object name (QOM path component)
 #
@@ -1339,8 +1336,7 @@
 
 ##
 # @NetworkClientInfo:
-#
-# Information about a network client.
+#     Information about a network client.
 #
 # @name: unique network client identifier
 #
@@ -1369,8 +1365,7 @@
 
 ##
 # @NetHubPortInfo:
-#
-# Information about a hub port.
+#     Information about a hub port.
 #
 # @name: hub port identifier
 #
@@ -1385,8 +1380,7 @@
 
 ##
 # @NetHubInfo:
-#
-# Information about a network hub.
+#     Information about a network hub.
 #
 # @id: hub identifier
 #
@@ -1401,8 +1395,7 @@
 
 ##
 # @NetworkInfo:
-#
-# Information about the network configuration.
+#     Information about the network configuration.
 #
 # @hubs: network hubs and their ports
 #
@@ -1417,8 +1410,7 @@
 
 ##
 # @x-query-network:
-#
-# Query the network configuration including hubs and clients.
+#     Query the network configuration including hubs and clients.
 #
 # Features:
 #
-- 
2.55.0

[PATCH v2 2/8] qapi: convert intro sections for unit tests

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
---
 tests/qapi-schema/doc-good.json                |  8 ++++----
 tests/qapi-schema/doc-good.out                 | 15 ++++++---------
 tests/qapi-schema/doc-interleaved-section.err  |  2 +-
 tests/qapi-schema/doc-interleaved-section.json |  3 +--
 4 files changed, 12 insertions(+), 16 deletions(-)

diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index fac13425b72..d9a84ccd729 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -94,10 +94,9 @@
 
 ##
 # @Variant1:
+#     A paragraph
 #
-# A paragraph
-#
-# Another paragraph
+#     Another paragraph
 #
 # @var1 is undocumented
 #
@@ -206,7 +205,8 @@
 
 ##
 # @cmd-boxed:
-# If you're bored enough to read this, go see a video of boxed cats
+#     If you're bored enough to read this, go see a video of boxed
+#     cats
 #
 # Features:
 # @cmd-feat1: a feature
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index 371dd25ffc7..eaaf119dea8 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -126,15 +126,13 @@ doc symbol=Base
  minimally indented
 doc symbol=Variant1
     Intro
+    A paragraph
 
-    Plain
-A paragraph
-
-Another paragraph
-
-@var1 is undocumented
+    Another paragraph
     Member=var1
 
+    Plain
+@var1 is undocumented
     Feature=variant1-feat
 a feature
     Feature=member-feat
@@ -213,9 +211,8 @@ Note::
 2.10
 doc symbol=cmd-boxed
     Intro
-
-    Plain
-If you're bored enough to read this, go see a video of boxed cats
+    If you're bored enough to read this, go see a video of boxed
+    cats
     Feature=cmd-feat1
 a feature
     Feature=cmd-feat2
diff --git a/tests/qapi-schema/doc-interleaved-section.err b/tests/qapi-schema/doc-interleaved-section.err
index e5d1ef54c1b..85f01fa57a7 100644
--- a/tests/qapi-schema/doc-interleaved-section.err
+++ b/tests/qapi-schema/doc-interleaved-section.err
@@ -1 +1 @@
-doc-interleaved-section.json:15:1: description of '@foobar:' follows a section
+doc-interleaved-section.json:14:1: description of '@foobar:' follows a section
diff --git a/tests/qapi-schema/doc-interleaved-section.json b/tests/qapi-schema/doc-interleaved-section.json
index eec01ed5650..bc0937b8601 100644
--- a/tests/qapi-schema/doc-interleaved-section.json
+++ b/tests/qapi-schema/doc-interleaved-section.json
@@ -2,8 +2,7 @@
 
 ##
 # @TestStruct:
-#
-# body
+#     body
 #
 # @integer: foo
 #           blah
-- 
2.55.0

[PATCH v2 3/8] qapi: convert trivial intros for qga/qapi-schema.json

[John Snow]

These are all single-sentence introductions immediately followed by a
non-plaintext section; no new insertion point is created.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qga/qapi-schema.json | 137 +++++++++++++++----------------------------
 1 file changed, 48 insertions(+), 89 deletions(-)

diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index 8cd0ba048b8..90110af5730 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -120,8 +120,7 @@
 
 ##
 # @guest-ping:
-#
-# Ping the guest agent, a non-error return implies success
+#     Ping the guest agent, a non-error return implies success
 #
 # Since: 0.15.0
 ##
@@ -129,9 +128,8 @@
 
 ##
 # @guest-get-time:
-#
-# Get the information about guest's System Time relative to the Epoch
-# of 1970-01-01 in UTC.
+#     Get the information about guest's System Time relative to the
+#     Epoch of 1970-01-01 in UTC.
 #
 # Returns: Time in nanoseconds.
 #
@@ -168,8 +166,7 @@
 
 ##
 # @GuestAgentCommandInfo:
-#
-# Information about guest agent commands.
+#     Information about guest agent commands.
 #
 # @name: name of the command
 #
@@ -185,8 +182,7 @@
 
 ##
 # @GuestAgentInfo:
-#
-# Information about guest agent.
+#     Information about guest agent.
 #
 # @version: guest agent version
 #
@@ -200,8 +196,7 @@
 
 ##
 # @guest-info:
-#
-# Get some information about the guest agent.
+#     Get some information about the guest agent.
 #
 # Since: 0.15.0
 ##
@@ -228,8 +223,7 @@
 
 ##
 # @guest-file-open:
-#
-# Open a file in the guest and retrieve a file handle for it
+#     Open a file in the guest and retrieve a file handle for it
 #
 # @path: Full path to the file in the guest to open.
 #
@@ -245,8 +239,7 @@
 
 ##
 # @guest-file-close:
-#
-# Close an open file in the guest
+#     Close an open file in the guest
 #
 # @handle: filehandle returned by `guest-file-open`
 #
@@ -257,8 +250,7 @@
 
 ##
 # @GuestFileRead:
-#
-# Result of guest agent file-read operation
+#     Result of guest agent file-read operation
 #
 # @count: number of bytes read (note: count is *before*
 #     base64-encoding is applied)
@@ -292,8 +284,7 @@
 
 ##
 # @GuestFileWrite:
-#
-# Result of guest agent file-write operation
+#     Result of guest agent file-write operation
 #
 # @count: number of bytes written (note: count is actual bytes
 #     written, after base64-decoding of provided buffer)
@@ -307,8 +298,7 @@
 
 ##
 # @guest-file-write:
-#
-# Write to an open file in the guest.
+#     Write to an open file in the guest.
 #
 # @handle: filehandle returned by `guest-file-open`
 #
@@ -325,8 +315,7 @@
 
 ##
 # @GuestFileSeek:
-#
-# Result of guest agent file-seek operation
+#     Result of guest agent file-seek operation
 #
 # @position: current file position
 #
@@ -339,8 +328,7 @@
 
 ##
 # @QGASeek:
-#
-# Symbolic names for use in `guest-file-seek`
+#     Symbolic names for use in `guest-file-seek`
 #
 # @set: Set to the specified offset (same effect as 'whence':0)
 #
@@ -354,8 +342,7 @@
 
 ##
 # @GuestFileWhence:
-#
-# Controls the meaning of offset to `guest-file-seek`.
+#     Controls the meaning of offset to `guest-file-seek`.
 #
 # @value: Integral value (0 for set, 1 for cur, 2 for end), available
 #     for historical reasons, and might differ from the host's or
@@ -390,8 +377,7 @@
 
 ##
 # @guest-file-flush:
-#
-# Write file changes buffered in userspace to disk/kernel buffers
+#     Write file changes buffered in userspace to disk/kernel buffers
 #
 # @handle: filehandle returned by `guest-file-open`
 #
@@ -402,8 +388,7 @@
 
 ##
 # @GuestFsfreezeStatus:
-#
-# An enumeration of filesystem freeze states
+#     An enumeration of filesystem freeze states
 #
 # @thawed: filesystems thawed/unfrozen
 #
@@ -476,8 +461,7 @@
 
 ##
 # @guest-fsfreeze-thaw:
-#
-# Unfreeze all frozen guest filesystems
+#     Unfreeze all frozen guest filesystems
 #
 # Returns: Number of file systems thawed by this call
 #
@@ -524,8 +508,8 @@
 
 ##
 # @guest-fstrim:
-#
-# Discard (or "trim") blocks which are not in use by the filesystem.
+#     Discard (or "trim") blocks which are not in use by the
+#     filesystem.
 #
 # @minimum: Minimum contiguous free range to discard, in bytes.  Free
 #     ranges smaller than this may be ignored (this is a hint and the
@@ -649,8 +633,7 @@
 
 ##
 # @GuestIpAddressType:
-#
-# An enumeration of supported IP address types
+#     An enumeration of supported IP address types
 #
 # @ipv4: IP version 4
 #
@@ -735,8 +718,7 @@
 
 ##
 # @guest-network-get-interfaces:
-#
-# Get list of guest IP addresses, MAC addresses and netmasks.
+#     Get list of guest IP addresses, MAC addresses and netmasks.
 #
 # Since: 1.1
 ##
@@ -782,9 +764,8 @@
 
 ##
 # @guest-set-vcpus:
-#
-# Attempt to reconfigure (currently: enable/disable) logical
-# processors inside the guest.
+#     Attempt to reconfigure (currently: enable/disable) logical
+#     processors inside the guest.
 #
 # @vcpus: The logical processors to be reconfigured.  This list is
 #     processed node by node in order.  In each node @logical-id is
@@ -825,8 +806,7 @@
 
 ##
 # @GuestDiskBusType:
-#
-# An enumeration of bus type of disks
+#     An enumeration of bus type of disks
 #
 # @ide: IDE disks
 #
@@ -984,8 +964,7 @@
 
 ##
 # @GuestDiskSmart:
-#
-# Disk type related smart information.
+#     Disk type related smart information.
 #
 # @type: disk bus type
 #
@@ -1147,8 +1126,7 @@
 
 ##
 # @GuestMemoryBlockResponseType:
-#
-# An enumeration of memory block operation result.
+#     An enumeration of memory block operation result.
 #
 # @success: the operation of online/offline memory block is
 #     successful.
@@ -1191,9 +1169,8 @@
 
 ##
 # @guest-set-memory-blocks:
-#
-# Attempt to reconfigure (currently: enable/disable) state of memory
-# blocks inside the guest.
+#     Attempt to reconfigure (currently: enable/disable) state of
+#     memory blocks inside the guest.
 #
 # @mem-blks: The memory blocks to be reconfigured.  This list is
 #     processed node by node in order.  In each node @phys-index is
@@ -1236,8 +1213,7 @@
 
 ##
 # @guest-get-memory-block-info:
-#
-# Get information relating to guest memory blocks.
+#     Get information relating to guest memory blocks.
 #
 # Since: 2.3
 ##
@@ -1303,8 +1279,7 @@
 
 ##
 # @GuestExecCaptureOutputMode:
-#
-# An enumeration of `guest-exec` capture modes.
+#     An enumeration of `guest-exec` capture modes.
 #
 # @none: do not capture any output
 #
@@ -1326,8 +1301,7 @@
 
 ##
 # @GuestExecCaptureOutput:
-#
-# Controls what `guest-exec` output gets captures.
+#     Controls what `guest-exec` output gets captures.
 #
 # @flag: captures both stdout and stderr if true.  Equivalent to
 #     `GuestExecCaptureOutputMode`::all.  (since 2.5)
@@ -1342,8 +1316,7 @@
 
 ##
 # @guest-exec:
-#
-# Execute a command in the guest
+#     Execute a command in the guest
 #
 # @path: path or executable name to execute
 #
@@ -1411,8 +1384,7 @@
 
 ##
 # @guest-get-users:
-#
-# Retrieves a list of currently active users on the VM.
+#     Retrieves a list of currently active users on the VM.
 #
 # Returns: A unique list of users.
 #
@@ -1438,8 +1410,7 @@
 
 ##
 # @guest-get-timezone:
-#
-# Retrieves the timezone information from the guest.
+#     Retrieves the timezone information from the guest.
 #
 # Since: 2.10
 ##
@@ -1512,8 +1483,7 @@
 
 ##
 # @guest-get-osinfo:
-#
-# Retrieve guest operating system information
+#     Retrieve guest operating system information
 #
 # Since: 2.10
 ##
@@ -1544,8 +1514,7 @@
 
 ##
 # @GuestDeviceId:
-#
-# Id of the device
+#     Id of the device
 #
 # @type: device type
 #
@@ -1581,8 +1550,7 @@
 
 ##
 # @guest-get-devices:
-#
-# Retrieve information about device drivers in Windows guest
+#     Retrieve information about device drivers in Windows guest
 #
 # Since: 5.2
 ##
@@ -1605,9 +1573,8 @@
 
 ##
 # @guest-ssh-get-authorized-keys:
-#
-# Return the public keys from user .ssh/authorized_keys on Unix
-# systems (not implemented for other systems).
+#     Return the public keys from user .ssh/authorized_keys on Unix
+#     systems (not implemented for other systems).
 #
 # @username: the user account to add the authorized keys
 #
@@ -1620,9 +1587,8 @@
 
 ##
 # @guest-ssh-add-authorized-keys:
-#
-# Append public keys to user .ssh/authorized_keys on Unix systems (not
-# implemented for other systems).
+#     Append public keys to user .ssh/authorized_keys on Unix systems
+#     (not implemented for other systems).
 #
 # @username: the user account to add the authorized keys
 #
@@ -1736,8 +1702,7 @@
 
 ##
 # @guest-get-diskstats:
-#
-# Retrieve information about disk stats.
+#     Retrieve information about disk stats.
 #
 # Returns: List of disk stats of guest.
 #
@@ -1750,8 +1715,7 @@
 
 ##
 # @GuestCpuStatsType:
-#
-# Guest operating systems supporting CPU statistics
+#     Guest operating systems supporting CPU statistics
 #
 # @linux: Linux
 #
@@ -1763,8 +1727,7 @@
 
 ##
 # @GuestLinuxCpuStats:
-#
-# CPU statistics of Linux
+#     CPU statistics of Linux
 #
 # @cpu: CPU index in guest OS
 #
@@ -1808,8 +1771,7 @@
 
 ##
 # @GuestCpuStats:
-#
-# Get statistics of each CPU in millisecond.
+#     Get statistics of each CPU in millisecond.
 #
 # @type: guest operating system
 #
@@ -1823,8 +1785,7 @@
 
 ##
 # @guest-get-cpustats:
-#
-# Retrieve information about CPU stats.
+#     Retrieve information about CPU stats.
 #
 # Returns: List of CPU stats of guest.
 #
@@ -1837,8 +1798,7 @@
 
 ##
 # @GuestLoadAverage:
-#
-# Statistics about process load information
+#     Statistics about process load information
 #
 # @load1m: 1-minute load avage
 #
@@ -1941,8 +1901,7 @@
 
 ##
 # @guest-network-get-route:
-#
-# Retrieve information about route of network.
+#     Retrieve information about route of network.
 #
 # Returns: List of route info of guest.
 #
-- 
2.55.0

[PATCH v2 4/8] qapi: convert simple intros for qga/qapi-schema.json

[John Snow]

These are all single-paragraph introductions immediately followed by a
non-plaintext section, so no new insertion point is created by this
conversion.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qga/qapi-schema.json | 40 ++++++++++++++++++----------------------
 1 file changed, 18 insertions(+), 22 deletions(-)

diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index 90110af5730..b592b14a011 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -205,9 +205,9 @@
 
 ##
 # @guest-shutdown:
-#
-# Initiate guest-activated shutdown.  Note: this is an asynchronous
-# shutdown request, with no guarantee of successful shutdown.
+#     Initiate guest-activated shutdown.  Note: this is an
+#     asynchronous shutdown request, with no guarantee of successful
+#     shutdown.
 #
 # @mode: "halt", "powerdown" (default), or "reboot"
 #
@@ -266,10 +266,10 @@
 
 ##
 # @guest-file-read:
-#
-# Read from an open file in the guest.  Data will be base64-encoded.
-# As this command is just for limited, ad-hoc debugging, such as log
-# file access, the number of bytes to read is limited to 48 MB.
+#     Read from an open file in the guest.  Data will be
+#     base64-encoded.  As this command is just for limited, ad-hoc
+#     debugging, such as log file access, the number of bytes to read
+#     is limited to 48 MB.
 #
 # @handle: filehandle returned by `guest-file-open`
 #
@@ -357,10 +357,9 @@
 
 ##
 # @guest-file-seek:
-#
-# Seek to a position in the file, as with fseek(), and return the
-# current file position afterward.  Also encapsulates ftell()'s
-# functionality, with offset=0 and whence=1.
+#     Seek to a position in the file, as with fseek(), and return the
+#     current file position afterward.  Also encapsulates ftell()'s
+#     functionality, with offset=0 and whence=1.
 #
 # @handle: filehandle returned by `guest-file-open`
 #
@@ -1254,10 +1253,9 @@
 
 ##
 # @guest-exec-status:
-#
-# Check status of process associated with PID retrieved via
-# `guest-exec`.  Reap the process and associated metadata if it has
-# exited.
+#     Check status of process associated with PID retrieved via
+#     `guest-exec`.  Reap the process and associated metadata if it
+#     has exited.
 #
 # @pid: pid returned from `guest-exec`
 #
@@ -1605,10 +1603,9 @@
 
 ##
 # @guest-ssh-remove-authorized-keys:
-#
-# Remove public keys from the user .ssh/authorized_keys on Unix
-# systems (not implemented for other systems).  It's not an error if
-# the key is already missing.
+#     Remove public keys from the user .ssh/authorized_keys on Unix
+#     systems (not implemented for other systems).  It's not an error
+#     if the key is already missing.
 #
 # @username: the user account to remove the authorized keys
 #
@@ -1838,9 +1835,8 @@
 
 ##
 # @GuestNetworkRoute:
-#
-# Route information.  Supported on Linux (since 9.1) and Windows
-# (since 11.0).
+#     Route information.  Supported on Linux (since 9.1) and Windows
+#     (since 11.0).
 #
 # @iface: The destination network or host's egress network interface
 #     in the routing table
-- 
2.55.0

[PATCH v2 5/8] qapi: split intros at natural cutoff points for qga/qapi-schema.json

[John Snow]

Note that these intro conversions introduce a new intro/details split
point. This new split point may or may not change the rendered output
depending on if any documentation is auto-generated and inserted for
this definition.

This has tangible effects on how @guest-fsfreeze-status documentation
is rendered, while the other two appear unchanged.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qga/qapi-schema.json | 11 ++++-------
 1 file changed, 4 insertions(+), 7 deletions(-)

diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index b592b14a011..19b0958b84e 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -401,8 +401,7 @@
 
 ##
 # @guest-fsfreeze-status:
-#
-# Get guest fsfreeze state.
+#     Get guest fsfreeze state.
 #
 # .. note:: This may fail to properly report the current state as a
 #    result of some other guest processes having issued an fs
@@ -925,9 +924,8 @@
 
 ##
 # @GuestNVMeSmart:
-#
-# NVMe smart information, based on NVMe specification, section
-# <SMART / Health Information (Log Identifier 02h)>
+#     NVMe smart information, based on NVMe specification, section
+#     <SMART / Health Information (Log Identifier 02h)>
 #
 # TODO: document members briefly
 #
@@ -1816,8 +1814,7 @@
 
 ##
 # @guest-get-load:
-#
-# Retrieve CPU process load information
+#     Retrieve CPU process load information
 #
 # .. note:: Windows does not have load average API, so QGA emulates it
 #    by calculating the average CPU usage in the last 1, 5, 15 minutes
-- 
2.55.0

[PATCH v2 6/8] qapi: split intros for qga/qapi-schema.json

[John Snow]

These intro section conversions all create a new insertion point that
follow the introduction, but precede what now constitutes the details
text. Like other intro section conversions, the details text will be
moved en-masse in a later patch.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qga/qapi-schema.json | 61 +++++++++++++++++++-------------------------
 1 file changed, 26 insertions(+), 35 deletions(-)

diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index 19b0958b84e..05fe4ea484d 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -48,9 +48,8 @@
 
 ##
 # @guest-sync-delimited:
-#
-# Echo back a unique integer value, and prepend to response a leading
-# sentinel byte (0xFF) the client can check scan for.
+#     Echo back a unique integer value, and prepend to response a
+#     leading sentinel byte (0xFF) the client can check scan for.
 #
 # This is used by clients talking to the guest agent over the wire to
 # ensure the stream is in sync and doesn't contain stale data from
@@ -83,8 +82,7 @@
 
 ##
 # @guest-sync:
-#
-# Echo back a unique integer value
+#     Echo back a unique integer value
 #
 # This is used by clients talking to the guest agent over the wire to
 # ensure the stream is in sync and doesn't contain stale data from
@@ -140,8 +138,7 @@
 
 ##
 # @guest-set-time:
-#
-# Set guest time.
+#     Set guest time.
 #
 # When a guest is paused or migrated to a file then loaded from that
 # file, the guest OS has no idea that there was a big gap in the time.
@@ -415,14 +412,14 @@
 
 ##
 # @guest-fsfreeze-freeze:
+#     Sync and freeze all freezable, local guest filesystems.  If this
+#     command succeeded, you may call `guest-fsfreeze-thaw` later to
+#     unfreeze.
 #
-# Sync and freeze all freezable, local guest filesystems.  If this
-# command succeeded, you may call `guest-fsfreeze-thaw` later to
-# unfreeze.
-#
-# On error, all filesystems will be thawed.  If no filesystems are
-# frozen as a result of this call, then `guest-fsfreeze-status` will
-# remain "thawed" and calling `guest-fsfreeze-thaw` is not necessary.
+#     On error, all filesystems will be thawed.  If no filesystems are
+#     frozen as a result of this call, then `guest-fsfreeze-status`
+#     will remain "thawed" and calling `guest-fsfreeze-thaw` is not
+#     necessary.
 #
 # Returns: Number of file systems currently frozen.
 #
@@ -438,11 +435,10 @@
 
 ##
 # @guest-fsfreeze-freeze-list:
+#     Sync and freeze specified guest filesystems.  See also
+#     `guest-fsfreeze-freeze`.
 #
-# Sync and freeze specified guest filesystems.  See also
-# `guest-fsfreeze-freeze`.
-#
-# On error, all filesystems will be thawed.
+#     On error, all filesystems will be thawed.
 #
 # @mountpoints: an array of mountpoints of filesystems to be frozen.
 #     If omitted, every mounted filesystem is frozen.  Invalid mount
@@ -528,8 +524,7 @@
 
 ##
 # @guest-suspend-disk:
-#
-# Suspend guest to disk.
+#     Suspend guest to disk.
 #
 # This command attempts to suspend the guest using three strategies,
 # in this order:
@@ -558,8 +553,7 @@
 
 ##
 # @guest-suspend-ram:
-#
-# Suspend guest to ram.
+#     Suspend guest to ram.
 #
 # This command attempts to suspend the guest using three strategies,
 # in this order:
@@ -595,8 +589,7 @@
 
 ##
 # @guest-suspend-hybrid:
-#
-# Save guest state to disk and suspend to ram.
+#     Save guest state to disk and suspend to ram.
 #
 # This command attempts to suspend the guest by executing, in this
 # order:
@@ -746,10 +739,9 @@
 
 ##
 # @guest-get-vcpus:
+#     Retrieve the list of the guest's logical processors.
 #
-# Retrieve the list of the guest's logical processors.
-#
-# This is a read-only operation.
+#     This is a read-only operation.
 #
 # Returns: The list of all VCPUs the guest knows about.  Each VCPU is
 #     put on the list exactly once, but their order is unspecified.
@@ -1106,10 +1098,9 @@
 
 ##
 # @guest-get-memory-blocks:
+#     Retrieve the list of the guest's memory blocks.
 #
-# Retrieve the list of the guest's memory blocks.
-#
-# This is a read-only operation.
+#     This is a read-only operation.
 #
 # Returns: The list of all memory blocks the guest knows about.  Each
 #     memory block is put on the list exactly once, but their order is
@@ -1346,12 +1337,12 @@
 
 ##
 # @guest-get-host-name:
+#     Return a name for the machine.
 #
-# Return a name for the machine.
-#
-# The returned name is not necessarily a fully-qualified domain name,
-# or even present in DNS or some other name service at all.  It need
-# not even be unique on your local network or site, but usually it is.
+#     The returned name is not necessarily a fully-qualified domain
+#     name, or even present in DNS or some other name service at all.
+#     It need not even be unique on your local network or site, but
+#     usually it is.
 #
 # Returns: the host name of the machine
 #
-- 
2.55.0

[PATCH v2 7/8] qapi: convert intro sections for docs/interop/firmware.json

[John Snow]

All conversions in this patch do not create a new documentation
insertion point, except for one at the very end.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/interop/firmware.json | 76 ++++++++++++++++----------------------
 1 file changed, 31 insertions(+), 45 deletions(-)

diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json
index 421bee0e5ed..1efd32c6315 100644
--- a/docs/interop/firmware.json
+++ b/docs/interop/firmware.json
@@ -23,9 +23,8 @@
 
 ##
 # @FirmwareOSInterface:
-#
-# Lists the firmware-OS interface types provided by various firmware
-# that is commonly used with QEMU virtual machines.
+#     Lists the firmware-OS interface types provided by various
+#     firmware that is commonly used with QEMU virtual machines.
 #
 # @bios: Traditional x86 BIOS interface.  For example, firmware built
 #     from the SeaBIOS project usually provides this interface.
@@ -49,8 +48,7 @@
 
 ##
 # @FirmwareDevice:
-#
-# Defines the device types that firmware can be mapped into.
+#     Defines the device types that firmware can be mapped into.
 #
 # @flash: The firmware executable and its accompanying NVRAM file are
 #     to be mapped into a pflash chip each.
@@ -75,9 +73,8 @@
 
 ##
 # @FirmwareArchitecture:
-#
-# Enumeration of architectures for which Qemu uses additional firmware
-# files.
+#     Enumeration of architectures for which Qemu uses additional
+#     firmware files.
 #
 # @aarch64: 64-bit Arm.
 #
@@ -98,8 +95,7 @@
 
 ##
 # @FirmwareTarget:
-#
-# Defines the machine types that firmware may execute on.
+#     Defines the machine types that firmware may execute on.
 #
 # @architecture: Determines the emulation target (the QEMU system
 #     emulator) that can execute the firmware.
@@ -121,9 +117,8 @@
 
 ##
 # @FirmwareFeature:
-#
-# Defines the features that firmware may support, and the platform
-# requirements that firmware may present.
+#     Defines the features that firmware may support, and the platform
+#     requirements that firmware may present.
 #
 # @acpi-s3: The firmware supports S3 sleep (suspend to RAM), as
 #     defined in the ACPI specification.  On the "pc-i440fx-*" machine
@@ -236,8 +231,7 @@
 
 ##
 # @FirmwareFormat:
-#
-# Formats that are supported for firmware images.
+#     Formats that are supported for firmware images.
 #
 # @raw: Raw disk image format.
 #
@@ -250,12 +244,11 @@
 
 ##
 # @FirmwareFlashFile:
-#
-# Defines common properties that are necessary for loading a firmware
-# file into a pflash chip.  The corresponding QEMU command line option
-# is "-drive file=@filename,format=@format".  Note however that the
-# option-argument shown here is incomplete; it is completed under
-# @FirmwareMappingFlash.
+#     Defines common properties that are necessary for loading a
+#     firmware file into a pflash chip.  The corresponding QEMU
+#     command line option is "-drive file=@filename,format=@format".
+#     Note however that the option-argument shown here is incomplete;
+#     it is completed under @FirmwareMappingFlash.
 #
 # @filename: Specifies the filename on the host filesystem where the
 #     firmware file can be found.
@@ -272,9 +265,8 @@
 
 ##
 # @FirmwareFlashMode:
-#
-# Describes how the firmware build handles code versus variable
-# persistence.
+#     Describes how the firmware build handles code versus variable
+#     persistence.
 #
 # @split: the executable file contains code while the NVRAM template
 #     provides variable storage.  The executable must be configured
@@ -298,9 +290,9 @@
 
 ##
 # @FirmwareMappingFlash:
-#
-# Describes loading and mapping properties for the firmware executable
-# and its accompanying NVRAM file, when @FirmwareDevice is @flash.
+#     Describes loading and mapping properties for the firmware
+#     executable and its accompanying NVRAM file, when @FirmwareDevice
+#     is @flash.
 #
 # @mode: Describes how the firmware build handles code versus variable
 #     storage.  If not present, it must be treated as if it was
@@ -357,9 +349,8 @@
 
 ##
 # @FirmwareMappingKernel:
-#
-# Describes loading and mapping properties for the firmware
-# executable, when @FirmwareDevice is @kernel.
+#     Describes loading and mapping properties for the firmware
+#     executable, when @FirmwareDevice is @kernel.
 #
 # @filename: Identifies the firmware executable.  The firmware
 #     executable may be shared by multiple virtual machine
@@ -373,9 +364,8 @@
 
 ##
 # @FirmwareMemoryUefiVars:
-#
-# Contains information needed to set up the "uefi-vars" device
-# to provide UEFI variable store access to the firmware.
+#     Contains information needed to set up the "uefi-vars" device to
+#     provide UEFI variable store access to the firmware.
 #
 # @template: The path to the UEFI JSON variable store template
 #     compatible with the firmware.  Management software instantiates
@@ -406,9 +396,8 @@
 
 ##
 # @FirmwareMappingMemory:
-#
-# Describes loading and mapping properties for the firmware
-# executable, when @FirmwareDevice is @memory.
+#     Describes loading and mapping properties for the firmware
+#     executable, when @FirmwareDevice is @memory.
 #
 # @filename: Identifies the firmware executable.  The firmware
 #     executable may be shared by multiple virtual machine
@@ -430,9 +419,8 @@
 
 ##
 # @FirmwareMappingIgvm:
-#
-# Describes loading and mapping properties for the firmware
-# executable, when @FirmwareDevice is @igvm.
+#     Describes loading and mapping properties for the firmware
+#     executable, when @FirmwareDevice is @igvm.
 #
 # @filename: Identifies the IGVM file containing the firmware
 #     executable along with other information used to configure the
@@ -448,9 +436,8 @@
 
 ##
 # @FirmwareMapping:
-#
-# Provides a discriminated structure for firmware to describe its
-# loading / mapping properties.
+#     Provides a discriminated structure for firmware to describe its
+#     loading / mapping properties.
 #
 # @device: Selects the device type that the firmware must be mapped
 #     into.
@@ -467,9 +454,8 @@
 
 ##
 # @Firmware:
-#
-# Describes a firmware (or a firmware use case) to management
-# software.
+#     Describes a firmware (or a firmware use case) to management
+#     software.
 #
 # It is possible for multiple @Firmware elements to match the search
 # criteria of management software.  Applications thus need rules to
-- 
2.55.0

[PATCH v2 8/8] qapi: convert intro sections for docs/interop/vhost-user.json

[John Snow]

All conversions in this patch do not add a new insertion point, except
for the very last conversion.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/interop/vhost-user.json | 27 +++++++++------------------
 1 file changed, 9 insertions(+), 18 deletions(-)

diff --git a/docs/interop/vhost-user.json b/docs/interop/vhost-user.json
index 29c84e86e55..65e681a166a 100644
--- a/docs/interop/vhost-user.json
+++ b/docs/interop/vhost-user.json
@@ -17,8 +17,7 @@
 
 ##
 # @VHostUserBackendType:
-#
-# List the various vhost user backend types.
+#     List the various vhost user backend types.
 #
 # @9p: 9p virtio console
 #
@@ -75,8 +74,7 @@
 
 ##
 # @VHostUserBackendBlockFeature:
-#
-# List of vhost user "block" features.
+#     List of vhost user "block" features.
 #
 # @read-only: The --read-only command line option is supported.
 #
@@ -91,8 +89,7 @@
 
 ##
 # @VHostUserBackendCapabilitiesBlock:
-#
-# Capabilities reported by vhost user "block" backends
+#     Capabilities reported by vhost user "block" backends
 #
 # @features: list of supported features.
 #
@@ -107,8 +104,7 @@
 
 ##
 # @VHostUserBackendInputFeature:
-#
-# List of vhost user "input" features.
+#     List of vhost user "input" features.
 #
 # @evdev-path: The --evdev-path command line option is supported.
 #
@@ -123,8 +119,7 @@
 
 ##
 # @VHostUserBackendCapabilitiesInput:
-#
-# Capabilities reported by vhost user "input" backends
+#     Capabilities reported by vhost user "input" backends
 #
 # @features: list of supported features.
 #
@@ -139,8 +134,7 @@
 
 ##
 # @VHostUserBackendGPUFeature:
-#
-# List of vhost user "gpu" features.
+#     List of vhost user "gpu" features.
 #
 # @render-node: The --render-node command line option is supported.
 #
@@ -155,8 +149,7 @@
 
 ##
 # @VHostUserBackendCapabilitiesGPU:
-#
-# Capabilities reported by vhost user "gpu" backends.
+#     Capabilities reported by vhost user "gpu" backends.
 #
 # @features: list of supported features.
 #
@@ -171,8 +164,7 @@
 
 ##
 # @VHostUserBackendCapabilities:
-#
-# Capabilities reported by vhost user backends.
+#     Capabilities reported by vhost user backends.
 #
 # @type: The vhost user backend type.
 #
@@ -190,8 +182,7 @@
 
 ##
 # @VhostUserBackend:
-#
-# Describes a vhost user backend to management software.
+#     Describes a vhost user backend to management software.
 #
 # It is possible for multiple @VhostUserBackend elements to match the
 # search criteria of management software.  Applications thus need
-- 
2.55.0

Re: [PATCH v2 2/8] qapi: convert intro sections for unit tests

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  tests/qapi-schema/doc-good.json                |  8 ++++----
>  tests/qapi-schema/doc-good.out                 | 15 ++++++---------
>  tests/qapi-schema/doc-interleaved-section.err  |  2 +-
>  tests/qapi-schema/doc-interleaved-section.json |  3 +--
>  4 files changed, 12 insertions(+), 16 deletions(-)
>
> diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
> index fac13425b72..d9a84ccd729 100644
> --- a/tests/qapi-schema/doc-good.json
> +++ b/tests/qapi-schema/doc-good.json
> @@ -94,10 +94,9 @@
>  
>  ##
>  # @Variant1:
> +#     A paragraph
>  #
> -# A paragraph
> -#
> -# Another paragraph
> +#     Another paragraph
>  #
>  # @var1 is undocumented
>  #

This creates a split.  doc-good.out and doc-good.txt need an update.
You got the former and missed the latter (appended) Happy to fix up in
my tree.

> @@ -206,7 +205,8 @@
>  
>  ##
>  # @cmd-boxed:
> -# If you're bored enough to read this, go see a video of boxed cats
> +#     If you're bored enough to read this, go see a video of boxed
> +#     cats
>  #
>  # Features:
>  # @cmd-feat1: a feature
> diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
> index 371dd25ffc7..eaaf119dea8 100644
> --- a/tests/qapi-schema/doc-good.out
> +++ b/tests/qapi-schema/doc-good.out
> @@ -126,15 +126,13 @@ doc symbol=Base
>   minimally indented
>  doc symbol=Variant1
>      Intro
> +    A paragraph
>  
> -    Plain
> -A paragraph
> -
> -Another paragraph
> -
> -@var1 is undocumented
> +    Another paragraph
>      Member=var1
>  
> +    Plain
> +@var1 is undocumented
>      Feature=variant1-feat
>  a feature
>      Feature=member-feat
> @@ -213,9 +211,8 @@ Note::
>  2.10
>  doc symbol=cmd-boxed
>      Intro
> -
> -    Plain
> -If you're bored enough to read this, go see a video of boxed cats
> +    If you're bored enough to read this, go see a video of boxed
> +    cats
>      Feature=cmd-feat1
>  a feature
>      Feature=cmd-feat2
> diff --git a/tests/qapi-schema/doc-interleaved-section.err b/tests/qapi-schema/doc-interleaved-section.err
> index e5d1ef54c1b..85f01fa57a7 100644
> --- a/tests/qapi-schema/doc-interleaved-section.err
> +++ b/tests/qapi-schema/doc-interleaved-section.err
> @@ -1 +1 @@
> -doc-interleaved-section.json:15:1: description of '@foobar:' follows a section
> +doc-interleaved-section.json:14:1: description of '@foobar:' follows a section
> diff --git a/tests/qapi-schema/doc-interleaved-section.json b/tests/qapi-schema/doc-interleaved-section.json
> index eec01ed5650..bc0937b8601 100644
> --- a/tests/qapi-schema/doc-interleaved-section.json
> +++ b/tests/qapi-schema/doc-interleaved-section.json
> @@ -2,8 +2,7 @@
>  
>  ##
>  # @TestStruct:
> -#
> -# body
> +#     body
>  #
>  # @integer: foo
>  #           blah

diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt
index 74b73681d3..ba089a7f94 100644
--- a/tests/qapi-schema/doc-good.txt
+++ b/tests/qapi-schema/doc-good.txt
@@ -65,11 +65,11 @@ Object Variant1
 
    Another paragraph
 
-   "var1" is undocumented
-
    Members:
       * **var1** ("string") -- Not documented
 
+   "var1" is undocumented
+
    Features:
       * **variant1-feat** -- a feature
 

Re: [PATCH v2 5/8] qapi: split intros at natural cutoff points for qga/qapi-schema.json

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> Note that these intro conversions introduce a new intro/details split
> point. This new split point may or may not change the rendered output
> depending on if any documentation is auto-generated and inserted for
> this definition.
>
> This has tangible effects on how @guest-fsfreeze-status documentation
> is rendered, while the other two appear unchanged.

Doesn't say how it changes, and it's not visible in the patch.  Suggest

  How @guest-fsfreeze-status documentation is rendered improves
  slightly: "Note:" moves from above "Return" to below.  The other
  conversions don't change rendered documentation.

>
> Signed-off-by: John Snow <jsnow@redhat.com>

Re: [PATCH v2 0/8] qapi: convert intros for qga, firmware, etc

[Markus Armbruster]

Series
Reviewed-by: Markus Armbruster <armbru@redhat.com>

Re: [PATCH v2 0/8] qapi: convert intros for qga, firmware, etc

[Markus Armbruster]

Markus Armbruster <armbru@redhat.com> writes:

> Series
> Reviewed-by: Markus Armbruster <armbru@redhat.com>

With the update to tests/qapi-schema/doc-good.txt squashed into PATCH 2,
of course.  I'll also make the commit message tweak for PATCH 5 if you
like it.

Re: [PATCH v2 2/8] qapi: convert intro sections for unit tests

[John Snow]

On Wed, Sep 23, 2026 at 2:07 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> John Snow <jsnow@redhat.com> writes:
>
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> >  tests/qapi-schema/doc-good.json                |  8 ++++----
> >  tests/qapi-schema/doc-good.out                 | 15 ++++++---------
> >  tests/qapi-schema/doc-interleaved-section.err  |  2 +-
> >  tests/qapi-schema/doc-interleaved-section.json |  3 +--
> >  4 files changed, 12 insertions(+), 16 deletions(-)
> >
> > diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
> > index fac13425b72..d9a84ccd729 100644
> > --- a/tests/qapi-schema/doc-good.json
> > +++ b/tests/qapi-schema/doc-good.json
> > @@ -94,10 +94,9 @@
> >
> >  ##
> >  # @Variant1:
> > +#     A paragraph
> >  #
> > -# A paragraph
> > -#
> > -# Another paragraph
> > +#     Another paragraph
> >  #
> >  # @var1 is undocumented
> >  #
>
> This creates a split.  doc-good.out and doc-good.txt need an update.
> You got the former and missed the latter (appended) Happy to fix up in
> my tree.

Yes, please. I think I updated the wrong file (build system copy and
not the source file) and didn't notice.

>
> > @@ -206,7 +205,8 @@
> >
> >  ##
> >  # @cmd-boxed:
> > -# If you're bored enough to read this, go see a video of boxed cats
> > +#     If you're bored enough to read this, go see a video of boxed
> > +#     cats
> >  #
> >  # Features:
> >  # @cmd-feat1: a feature
> > diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
> > index 371dd25ffc7..eaaf119dea8 100644
> > --- a/tests/qapi-schema/doc-good.out
> > +++ b/tests/qapi-schema/doc-good.out
> > @@ -126,15 +126,13 @@ doc symbol=Base
> >   minimally indented
> >  doc symbol=Variant1
> >      Intro
> > +    A paragraph
> >
> > -    Plain
> > -A paragraph
> > -
> > -Another paragraph
> > -
> > -@var1 is undocumented
> > +    Another paragraph
> >      Member=var1
> >
> > +    Plain
> > +@var1 is undocumented
> >      Feature=variant1-feat
> >  a feature
> >      Feature=member-feat
> > @@ -213,9 +211,8 @@ Note::
> >  2.10
> >  doc symbol=cmd-boxed
> >      Intro
> > -
> > -    Plain
> > -If you're bored enough to read this, go see a video of boxed cats
> > +    If you're bored enough to read this, go see a video of boxed
> > +    cats
> >      Feature=cmd-feat1
> >  a feature
> >      Feature=cmd-feat2
> > diff --git a/tests/qapi-schema/doc-interleaved-section.err b/tests/qapi-schema/doc-interleaved-section.err
> > index e5d1ef54c1b..85f01fa57a7 100644
> > --- a/tests/qapi-schema/doc-interleaved-section.err
> > +++ b/tests/qapi-schema/doc-interleaved-section.err
> > @@ -1 +1 @@
> > -doc-interleaved-section.json:15:1: description of '@foobar:' follows a section
> > +doc-interleaved-section.json:14:1: description of '@foobar:' follows a section
> > diff --git a/tests/qapi-schema/doc-interleaved-section.json b/tests/qapi-schema/doc-interleaved-section.json
> > index eec01ed5650..bc0937b8601 100644
> > --- a/tests/qapi-schema/doc-interleaved-section.json
> > +++ b/tests/qapi-schema/doc-interleaved-section.json
> > @@ -2,8 +2,7 @@
> >
> >  ##
> >  # @TestStruct:
> > -#
> > -# body
> > +#     body
> >  #
> >  # @integer: foo
> >  #           blah
>
> diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt
> index 74b73681d3..ba089a7f94 100644
> --- a/tests/qapi-schema/doc-good.txt
> +++ b/tests/qapi-schema/doc-good.txt
> @@ -65,11 +65,11 @@ Object Variant1
>
>     Another paragraph
>
> -   "var1" is undocumented
> -
>     Members:
>        * **var1** ("string") -- Not documented
>
> +   "var1" is undocumented
> +
>     Features:
>        * **variant1-feat** -- a feature
>
>

Re: [PATCH v2 5/8] qapi: split intros at natural cutoff points for qga/qapi-schema.json

[John Snow]

On Wed, Sep 23, 2026 at 2:25 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> John Snow <jsnow@redhat.com> writes:
>
> > Note that these intro conversions introduce a new intro/details split
> > point. This new split point may or may not change the rendered output
> > depending on if any documentation is auto-generated and inserted for
> > this definition.
> >
> > This has tangible effects on how @guest-fsfreeze-status documentation
> > is rendered, while the other two appear unchanged.
>
> Doesn't say how it changes, and it's not visible in the patch.  Suggest
>
>   How @guest-fsfreeze-status documentation is rendered improves
>   slightly: "Note:" moves from above "Return" to below.  The other
>   conversions don't change rendered documentation.
>

Thank you, this is good.

> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
>

Re: [PATCH v2 0/8] qapi: convert intros for qga, firmware, etc

[John Snow]

On Wed, Sep 23, 2026 at 2:49 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> Markus Armbruster <armbru@redhat.com> writes:
>
> > Series
> > Reviewed-by: Markus Armbruster <armbru@redhat.com>
>
> With the update to tests/qapi-schema/doc-good.txt squashed into PATCH 2,
> of course.  I'll also make the commit message tweak for PATCH 5 if you
> like it.

Yes, please!