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

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

[John Snow]

One day I will send patches that do something else.
Today is not that day.

John Snow (9):
  qapi: convert remaining simple 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
  tests/qapi: generate output in source order

 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               |  10 +-
 tests/qapi-schema/doc-good.out                |  95 ++++---
 tests/qapi-schema/doc-interleaved-section.err |   2 +-
 .../qapi-schema/doc-interleaved-section.json  |   3 +-
 tests/qapi-schema/test-qapi.py                |   9 +-
 12 files changed, 206 insertions(+), 300 deletions(-)

-- 
2.55.0

[PATCH 1/9] qapi: convert remaining simple sections

[John Snow]

A few slipped in during the mass conversion, get those too.

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, 12 insertions(+), 23 deletions(-)

diff --git a/qapi/block.json b/qapi/block.json
index 13c47e1eb44..68d4e47d911 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -597,9 +597,8 @@
 
 ##
 # @x-qemu-io:
-#
-# Run a qemu-io command on a block device.  Take either a block
-# backend name or a qdev ID to identify the device.
+#     Run a qemu-io command on a block 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

Re: [PATCH 1/9] qapi: convert remaining simple sections

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> A few slipped in during the mass conversion, get those too.
>
> 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, 12 insertions(+), 23 deletions(-)
>
> diff --git a/qapi/block.json b/qapi/block.json
> index 13c47e1eb44..68d4e47d911 100644
> --- a/qapi/block.json
> +++ b/qapi/block.json
> @@ -597,9 +597,8 @@
>  
>  ##
>  # @x-qemu-io:
> -#
> -# Run a qemu-io command on a block device.  Take either a block
> -# backend name or a qdev ID to identify the device.
> +#     Run a qemu-io command on a block device.  Take either a block
> +#     backend name or a qdev ID to identify the device.

The second sentence is not intro, it's a constraint on arguments @device
and @qdev.

>  #
>  # @device: the block backend name, node-name to run the
>  #     command on.

[...]

[PATCH 3/9] 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 4/9] 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

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

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> 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.

Taking note of future work:

10. Review doc where the intro contains (variations of) "Note:".

>  #
>  # @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.

Not this patch's problem, but here goes anyway: numeric @whence values
like 1 are "available for historical reasons", the preferred value is
"cur".

>  #
>  # @handle: filehandle returned by `guest-file-open`
>  #

[...]

[PATCH 6/9] 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

Re: [PATCH 6/9] qapi: split intros for qga/qapi-schema.json

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> 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.

More of what I noted in earlier series:

3. Review and improve doc comments where the intro talks about failure
modes.

Moving on.

>  #
>  # 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.

Likewise.

>  #
>  # @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.

If a command is called "get something", it's certainly not supposed to
change something!

Not this patch's problem, moving on...

>  #
>  # 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.

Likewise.

>  #
>  # 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.

This should perhaps be worked into Returns: ...  Not this patch's
problem, moving on...

>  #
>  # Returns: the host name of the machine
>  #

[PATCH 7/9] 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

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

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> 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

[...]

> @@ -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.

This smells like it could use a split, but it doesn't really matter;
let's move on.

[...]

> @@ -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

This is the split you mentioned in the commit message.  Correct?

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

[John Snow]

On Tue, Sep 22, 2026 at 11:05 AM Markus Armbruster <armbru@redhat.com> wrote:
>
> John Snow <jsnow@redhat.com> writes:
>
> > 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
>
> [...]
>
> > @@ -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.
>
> This smells like it could use a split, but it doesn't really matter;
> let's move on.
>
> [...]
>
> > @@ -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
>
> This is the split you mentioned in the commit message.  Correct?

Yep. Plan is to move this considerably long plaintext section below
the fold when the ordering series hits.

[PATCH 8/9] 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 5/9] 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 generated for this definition.

Uh, we generate documentation for *all* definitions.

>
> 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

This one does affect rendered docs: the auto-generated Returns moves
from below the note to above, where it belongs.

> @@ -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

These don't.

A possible commit message correction:

  Note that these intro conversions introduce a new intro/details split
  point. Only the first one affects the rendered output.

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

[John Snow]

On Tue, Sep 22, 2026 at 10:53 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 generated for this definition.
>
> Uh, we generate documentation for *all* definitions.

I meant ... generated from the definition itself and inserted. We
don't "generate" documentation for every doc block.

>
> >
> > 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
>
> This one does affect rendered docs: the auto-generated Returns moves
> from below the note to above, where it belongs.
>
> > @@ -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
>
> These don't.
>
> A possible commit message correction:
>
>   Note that these intro conversions introduce a new intro/details split
>   point. Only the first one affects the rendered output.

Sure.

Re: [PATCH 2/9] 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                | 10 +++++-----
>  tests/qapi-schema/doc-good.out                 | 13 +++++--------
>  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..00721d5c522 100644
> --- a/tests/qapi-schema/doc-good.json
> +++ b/tests/qapi-schema/doc-good.json
> @@ -94,12 +94,11 @@
>  
>  ##
>  # @Variant1:
> +#     A paragraph
>  #
> -# A paragraph
> +#     Another paragraph
>  #
> -# Another paragraph
> -#
> -# @var1 is undocumented
> +#     @var1 is undocumented

Let's keep '@var1 is undocumented' plain.  That way, it stays close to
"author forgot the colon after the member name", which I find useful.

>  #
>  # Features:
>  # @variant1-feat: a feature
> @@ -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..8c0818a3f0d 100644
> --- a/tests/qapi-schema/doc-good.out
> +++ b/tests/qapi-schema/doc-good.out
> @@ -126,13 +126,11 @@ doc symbol=Base
>   minimally indented
>  doc symbol=Variant1
>      Intro
> +    A paragraph
>  
> -    Plain
> -A paragraph
> +    Another paragraph
>  
> -Another paragraph
> -
> -@var1 is undocumented
> +    @var1 is undocumented
>      Member=var1
>  
>      Feature=variant1-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

I'm mildly surprised that the intro's indentation isn't stripped.  Maybe
we discussed that already, and I forgot.  Anyway, it works, and changing
it is way out of scope right now.

> 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

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

[John Snow]

On Tue, Sep 22, 2026 at 1:06 PM 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                | 10 +++++-----
> >  tests/qapi-schema/doc-good.out                 | 13 +++++--------
> >  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..00721d5c522 100644
> > --- a/tests/qapi-schema/doc-good.json
> > +++ b/tests/qapi-schema/doc-good.json
> > @@ -94,12 +94,11 @@
> >
> >  ##
> >  # @Variant1:
> > +#     A paragraph
> >  #
> > -# A paragraph
> > +#     Another paragraph
> >  #
> > -# Another paragraph
> > -#
> > -# @var1 is undocumented
> > +#     @var1 is undocumented
>
> Let's keep '@var1 is undocumented' plain.  That way, it stays close to
> "author forgot the colon after the member name", which I find useful.

OK, but it will very soon be disallowed in that position; it will have
to be moved below Features et al, eventually. Making this change, but
heads up that it necessitates another patch in the order enforcement
series.

>
> >  #
> >  # Features:
> >  # @variant1-feat: a feature
> > @@ -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..8c0818a3f0d 100644
> > --- a/tests/qapi-schema/doc-good.out
> > +++ b/tests/qapi-schema/doc-good.out
> > @@ -126,13 +126,11 @@ doc symbol=Base
> >   minimally indented
> >  doc symbol=Variant1
> >      Intro
> > +    A paragraph
> >
> > -    Plain
> > -A paragraph
> > +    Another paragraph
> >
> > -Another paragraph
> > -
> > -@var1 is undocumented
> > +    @var1 is undocumented
> >      Member=var1
> >
> >      Feature=variant1-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
>
> I'm mildly surprised that the intro's indentation isn't stripped.  Maybe
> we discussed that already, and I forgot.  Anyway, it works, and changing
> it is way out of scope right now.

*searching resident databanks*

I think I was striving for minimal processing of the text prior to
handoff to sphinx for reasons of preserving accurate source
information.

qapidoc.py has this code:
```
    def visit_plaintext(self, section: QAPIDoc.Section) -> None:
        # Squelch empty paragraphs.
        if not section.text:
            return

        # Intro sections, which are indented in QAPI source, need to
        # be dedented to avoid accidental block quotes in ReST syntax.
        dedent = bool(section.kind == QAPIDoc.Kind.INTRO)
        self.ensure_blank_line()
        self.add_lines(section.text, section.info, dedent)
        self.ensure_blank_line()
```

As a result, the unit test plaintext versions retain that indentation.
This actually matches how we treat indentation for member text, which
is also preserved and represented in the plaintext test output!

Granted, now that I have excised the backwards compatibility demon
from qapidoc, it is possible we can conduct another audit on source
information preservation and some things might be able to be
simplified, but I think this is fine and good for now.

>
> > 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
>

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

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> On Tue, Sep 22, 2026 at 1:06 PM 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                | 10 +++++-----
>> >  tests/qapi-schema/doc-good.out                 | 13 +++++--------
>> >  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..00721d5c522 100644
>> > --- a/tests/qapi-schema/doc-good.json
>> > +++ b/tests/qapi-schema/doc-good.json
>> > @@ -94,12 +94,11 @@
>> >
>> >  ##
>> >  # @Variant1:
>> > +#     A paragraph
>> >  #
>> > -# A paragraph
>> > +#     Another paragraph
>> >  #
>> > -# Another paragraph
>> > -#
>> > -# @var1 is undocumented
>> > +#     @var1 is undocumented
>>
>> Let's keep '@var1 is undocumented' plain.  That way, it stays close to
>> "author forgot the colon after the member name", which I find useful.
>
> OK, but it will very soon be disallowed in that position; it will have
> to be moved below Features et al, eventually. Making this change, but
> heads up that it necessitates another patch in the order enforcement
> series.

Yes.

>> >  #
>> >  # Features:
>> >  # @variant1-feat: a feature
>> > @@ -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..8c0818a3f0d 100644
>> > --- a/tests/qapi-schema/doc-good.out
>> > +++ b/tests/qapi-schema/doc-good.out
>> > @@ -126,13 +126,11 @@ doc symbol=Base
>> >   minimally indented
>> >  doc symbol=Variant1
>> >      Intro
>> > +    A paragraph
>> >
>> > -    Plain
>> > -A paragraph
>> > +    Another paragraph
>> >
>> > -Another paragraph
>> > -
>> > -@var1 is undocumented
>> > +    @var1 is undocumented
>> >      Member=var1
>> >
>> >      Feature=variant1-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
>>
>> I'm mildly surprised that the intro's indentation isn't stripped.  Maybe
>> we discussed that already, and I forgot.  Anyway, it works, and changing
>> it is way out of scope right now.
>
> *searching resident databanks*
>
> I think I was striving for minimal processing of the text prior to
> handoff to sphinx for reasons of preserving accurate source
> information.
>
> qapidoc.py has this code:
> ```
>     def visit_plaintext(self, section: QAPIDoc.Section) -> None:
>         # Squelch empty paragraphs.
>         if not section.text:
>             return
>
>         # Intro sections, which are indented in QAPI source, need to
>         # be dedented to avoid accidental block quotes in ReST syntax.
>         dedent = bool(section.kind == QAPIDoc.Kind.INTRO)
>         self.ensure_blank_line()
>         self.add_lines(section.text, section.info, dedent)
>         self.ensure_blank_line()
> ```
>
> As a result, the unit test plaintext versions retain that indentation.
> This actually matches how we treat indentation for member text, which
> is also preserved and represented in the plaintext test output!
>
> Granted, now that I have excised the backwards compatibility demon
> from qapidoc, it is possible we can conduct another audit on source
> information preservation and some things might be able to be
> simplified, but I think this is fine and good for now.

Maybe, eventually.  You got far more interesting work piled up that I
want to merge.

[...]

Re: [PATCH 9/9] tests/qapi: generate output in source order

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> Rewrite the test doc generator to produce output in source order,
> instead of arbitrarily.

Really?  As far as I can tell, the patch changes format, but not order.

Dig, dig, ...  you already switched it to source order in commit
9606414d46 (tests/qapi: generate output in source order, 2026-06-11).

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

Re: [PATCH 9/9] tests/qapi: generate output in source order

[John Snow]

On Tue, Sep 22, 2026 at 1:10 PM Markus Armbruster <armbru@redhat.com> wrote:
>
> John Snow <jsnow@redhat.com> writes:
>
> > Rewrite the test doc generator to produce output in source order,
> > instead of arbitrarily.
>
> Really?  As far as I can tell, the patch changes format, but not order.
>
> Dig, dig, ...  you already switched it to source order in commit
> 9606414d46 (tests/qapi: generate output in source order, 2026-06-11).

Ah, funny! This is probably the leftover bits we didn't agree on at
the time and I didn't notice that this patch became anemic. Well, this
is just a preference patch now and not really strictly necessary. I
like seeing the "section=" text because it's a clue for me as I read
the text, but it's not really important, I'll scrap it unless you also
like the formatting change.

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

Re: [PATCH 9/9] tests/qapi: generate output in source order

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> On Tue, Sep 22, 2026 at 1:10 PM Markus Armbruster <armbru@redhat.com> wrote:
>>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > Rewrite the test doc generator to produce output in source order,
>> > instead of arbitrarily.
>>
>> Really?  As far as I can tell, the patch changes format, but not order.
>>
>> Dig, dig, ...  you already switched it to source order in commit
>> 9606414d46 (tests/qapi: generate output in source order, 2026-06-11).
>
> Ah, funny! This is probably the leftover bits we didn't agree on at
> the time and I didn't notice that this patch became anemic. Well, this
> is just a preference patch now and not really strictly necessary. I
> like seeing the "section=" text because it's a clue for me as I read
> the text, but it's not really important, I'll scrap it unless you also
> like the formatting change.

Let's stay focused on finishing the syntax conversion.  I'm willing to
review it later.

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

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

[John Snow]

On Mon, Sep 21, 2026 at 4:52 PM John Snow <jsnow@redhat.com> wrote:
>
> One day I will send patches that do something else.
> Today is not that day.
>
> John Snow (9):
>   qapi: convert remaining simple 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
>   tests/qapi: generate output in source order
>
>  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               |  10 +-
>  tests/qapi-schema/doc-good.out                |  95 ++++---
>  tests/qapi-schema/doc-interleaved-section.err |   2 +-
>  .../qapi-schema/doc-interleaved-section.json  |   3 +-
>  tests/qapi-schema/test-qapi.py                |   9 +-
>  12 files changed, 206 insertions(+), 300 deletions(-)
>
> --
> 2.55.0

Markus: assuming I should wait for your reviews on 3, 4, and 8 before
I send a revision.

--js

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

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> Markus: assuming I should wait for your reviews on 3, 4, and 8 before
> I send a revision.

Go ahead and send!