[PATCH 00/10] qapi: convert simple enum intro sections

[PATCH 00/10] qapi: convert simple enum intro sections

[John Snow]

Hello, this work converts "simple" intro sections for enum
definitions in the QAPI schema to use the new syntax. This is part of
our ongoing effort to add the mythical "inliner" to our generated QMP
documentation.

"simple" here is a non-technical distinction that means a single
paragraph of text followed by an existing section boundary that
naturally already delineates what comprises the intro.
(This is about 25% of the remaining conversions.)

If you are a non-QAPI maintainer who has been CC'd on this series,
there is likely very little for you to look at in this series. What
you need to know is that indented paragraphs become part of a
command's "intro" and will appear "above the fold" - above additional
detail in our generated QMP documentation (i.e. features, arguments,
return value, errors, etc) and anything else will eventually appear
"below the fold" - below the detail table, alongside examples, notes,
and more verbose prose.

As enum definitions cannot be inlined by any other definition, the
documentation text for enums will never be re-written or reproduced in
any other context. As such, the distinction between "intro" and
"details" are less important here, but the distinction does still
determine where auto-generated documentation will be inserted, if any:
features will always be inserted "after the intro". (Note that at
present, features do not have any stub text that is automatically
generated.)

John Snow (10):
  qapi: convert simple enum intros for vfio.json
  qapi: convert simple enum intros for machine-common.json
  qapi: convert simple enum intros for introspect.json
  qapi: convert simple enum intros for block.json
  qapi: convert simple enum intros for cypto.json
  qapi: convert simple enum intros for cxl.json
  qapi: convert simple enum intros for yank.json
  qapi: convert simple enum intros for migration.json
  qapi: convert simple enum intros for machine.json
  qapi: convert simple enum intros for block-core.json

 qapi/block-core.json     |  7 +++----
 qapi/block.json          |  9 ++++-----
 qapi/crypto.json         | 18 +++++++++---------
 qapi/cxl.json            | 27 ++++++++++++---------------
 qapi/introspect.json     |  5 ++---
 qapi/machine-common.json |  5 ++---
 qapi/machine.json        | 21 +++++++++------------
 qapi/migration.json      | 10 ++++------
 qapi/vfio.json           | 15 +++++++--------
 qapi/yank.json           |  5 ++---
 10 files changed, 54 insertions(+), 68 deletions(-)

-- 
2.55.0

[PATCH 01/10] qapi: convert simple enum intros for vfio.json

[John Snow]

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

diff --git a/qapi/vfio.json b/qapi/vfio.json
index 3d61fc38ecd..47fff8b979d 100644
--- a/qapi/vfio.json
+++ b/qapi/vfio.json
@@ -10,14 +10,13 @@
 
 ##
 # @QapiVfioMigrationState:
-#
-# An enumeration of the VFIO device migration states.  In addition to
-# the regular states, there are prepare states (with 'prepare' suffix)
-# which indicate that the device is just about to transition to the
-# corresponding state.  Note that seeing a prepare state for state X
-# doesn't guarantee that the next state will be X, as the state
-# transition can fail and the device may transition to a different
-# state instead.
+#     An enumeration of the VFIO device migration states.  In addition
+#     to the regular states, there are prepare states (with 'prepare'
+#     suffix) which indicate that the device is just about to
+#     transition to the corresponding state.  Note that seeing a
+#     prepare state for state X doesn't guarantee that the next state
+#     will be X, as the state transition can fail and the device may
+#     transition to a different state instead.
 #
 # @stop: The device is stopped.
 #
-- 
2.55.0

[PATCH 02/10] qapi: convert simple enum intros for machine-common.json

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/machine-common.json | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/qapi/machine-common.json b/qapi/machine-common.json
index fdb0e68d9e6..0b07811df07 100644
--- a/qapi/machine-common.json
+++ b/qapi/machine-common.json
@@ -63,9 +63,8 @@
 
 ##
 # @CacheLevelAndType:
-#
-# Caches a system may have.  The enumeration value here is the
-# combination of cache level and cache type.
+#     Caches a system may have.  The enumeration value here is the
+#     combination of cache level and cache type.
 #
 # @l1d: L1 data cache.
 #
-- 
2.55.0

[PATCH 03/10] qapi: convert simple enum intros for introspect.json

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/introspect.json | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/qapi/introspect.json b/qapi/introspect.json
index 172ed389997..bd42aac3358 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -55,9 +55,8 @@
 
 ##
 # @SchemaMetaType:
-#
-# This is a `SchemaInfo`'s meta type, i.e. the kind of entity it
-# describes.
+#     This is a `SchemaInfo`'s meta type, i.e. the kind of entity it
+#     describes.
 #
 # @builtin: a predefined type such as 'int' or 'bool'.
 #
-- 
2.55.0

[PATCH 04/10] qapi: convert simple enum intros for block.json

[John Snow]

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

diff --git a/qapi/block.json b/qapi/block.json
index 9569afc6e0f..e47592d5500 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -16,11 +16,10 @@
 
 ##
 # @BiosAtaTranslation:
-#
-# Policy that BIOS should use to interpret cylinder/head/sector
-# addresses.  Note that Bochs BIOS and SeaBIOS will not actually
-# translate logical CHS to physical; instead, they will use logical
-# block addressing.
+#     Policy that BIOS should use to interpret cylinder/head/sector
+#     addresses.  Note that Bochs BIOS and SeaBIOS will not actually
+#     translate logical CHS to physical; instead, they will use
+#     logical block addressing.
 #
 # @auto: If cylinder/heads/sizes are passed, choose between none and
 #     LBA depending on the size of the disk.  If they are not passed,
-- 
2.55.0

[PATCH 05/10] qapi: convert simple enum intros for cypto.json

[John Snow]

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

diff --git a/qapi/crypto.json b/qapi/crypto.json
index 5e395bc10c7..f85d1cebed3 100644
--- a/qapi/crypto.json
+++ b/qapi/crypto.json
@@ -10,10 +10,10 @@
 
 ##
 # @QCryptoTLSCredsEndpoint:
-#
-# The type of network endpoint that will be using the credentials.
-# Most types of credential require different setup / structures
-# depending on whether they will be used in a server versus a client.
+#     The type of network endpoint that will be using the credentials.
+#     Most types of credential require different setup / structures
+#     depending on whether they will be used in a server versus a
+#     client.
 #
 # @client: the network endpoint is acting as the client
 #
@@ -126,11 +126,11 @@
 
 ##
 # @QCryptoIVGenAlgo:
-#
-# The supported algorithms for generating initialization vectors for
-# full disk encryption.  The 'plain' generator should not be used for
-# disks with sector numbers larger than 2^32, except where
-# compatibility with pre-existing Linux dm-crypt volumes is required.
+#     The supported algorithms for generating initialization vectors
+#     for full disk encryption.  The 'plain' generator should not be
+#     used for disks with sector numbers larger than 2^32, except
+#     where compatibility with pre-existing Linux dm-crypt volumes is
+#     required.
 #
 # @plain: 64-bit sector number truncated to 32-bits
 #
-- 
2.55.0

[PATCH 06/10] qapi: convert simple enum intros for cxl.json

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/cxl.json | 27 ++++++++++++---------------
 1 file changed, 12 insertions(+), 15 deletions(-)

diff --git a/qapi/cxl.json b/qapi/cxl.json
index 58ad82c2dc7..82524f47cdf 100644
--- a/qapi/cxl.json
+++ b/qapi/cxl.json
@@ -9,9 +9,9 @@
 
 ##
 # @CxlEventLog:
-#
-# CXL has a number of separate event logs for different types of
-# events.  Each such event log is handled and signaled independently.
+#     CXL has a number of separate event logs for different types of
+#     events.  Each such event log is handled and signaled
+#     independently.
 #
 # @informational: Information Event Log
 #
@@ -296,10 +296,9 @@
 
 ##
 # @CxlUncorErrorType:
-#
-# Type of uncorrectable CXL error to inject.  These errors are
-# reported via an AER uncorrectable internal error with additional
-# information logged at the CXL device.
+#     Type of uncorrectable CXL error to inject.  These errors are
+#     reported via an AER uncorrectable internal error with additional
+#     information logged at the CXL device.
 #
 # @cache-data-parity: Data error such as data parity or data ECC error
 #     CXL.cache
@@ -463,10 +462,9 @@
 
 ##
 # @CxlExtentSelectionPolicy:
-#
-# The policy to use for selecting which extents comprise the added
-# capacity, as defined in Compute Express Link (CXL) Specification,
-# Revision 3.1, Table 7-70.
+#     The policy to use for selecting which extents comprise the added
+#     capacity, as defined in Compute Express Link (CXL)
+#     Specification, Revision 3.1, Table 7-70.
 #
 # @free: Device is responsible for allocating the requested memory
 #     capacity and is free to do this using any combination of
@@ -550,10 +548,9 @@
 
 ##
 # @CxlExtentRemovalPolicy:
-#
-# The policy to use for selecting which extents comprise the released
-# capacity, defined in the "Flags" field in Compute Express Link (CXL)
-# Specification, Revision 3.1, Table 7-71.
+#     The policy to use for selecting which extents comprise the
+#     released capacity, defined in the "Flags" field in Compute
+#     Express Link (CXL) Specification, Revision 3.1, Table 7-71.
 #
 # @tag-based: Extents are selected by the device based on tag, with
 #     no requirement for contiguous extents.
-- 
2.55.0

[PATCH 07/10] qapi: convert simple enum intros for yank.json

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/yank.json | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/qapi/yank.json b/qapi/yank.json
index 9a5aea82f1d..85a0c87719d 100644
--- a/qapi/yank.json
+++ b/qapi/yank.json
@@ -10,9 +10,8 @@
 
 ##
 # @YankInstanceType:
-#
-# An enumeration of yank instance types.  See `YankInstance` for more
-# information.
+#     An enumeration of yank instance types.  See `YankInstance` for
+#     more information.
 #
 # Since: 6.0
 ##
-- 
2.55.0

[PATCH 08/10] qapi: convert simple enum intros for migration.json

[John Snow]

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

diff --git a/qapi/migration.json b/qapi/migration.json
index 5fbd604f995..8096ef64682 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -788,9 +788,8 @@
 
 ##
 # @MigrationParameter:
-#
-# Migration parameters enumeration.  The enumeration values mirror the
-# members of @MigrationParameters.
+#     Migration parameters enumeration.  The enumeration values mirror
+#     the members of @MigrationParameters.
 #
 # Features:
 #
@@ -1756,9 +1755,8 @@
 
 ##
 # @DirtyRateMeasureMode:
-#
-# Method used to measure dirty page rate.  Differences between
-# available methods are explained in `calc-dirty-rate`.
+#     Method used to measure dirty page rate.  Differences between
+#     available methods are explained in `calc-dirty-rate`.
 #
 # @page-sampling: use page sampling
 #
-- 
2.55.0

[PATCH 09/10] qapi: convert simple enum intros for machine.json

[John Snow]

Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/machine.json | 21 +++++++++------------
 1 file changed, 9 insertions(+), 12 deletions(-)

diff --git a/qapi/machine.json b/qapi/machine.json
index cf905afd4f1..942d35d7275 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -15,12 +15,11 @@
 
 ##
 # @SysEmuTarget:
-#
-# The comprehensive enumeration of QEMU system emulation ("softmmu")
-# targets.  Run "./configure --help" in the project root directory,
-# and look for the \*-softmmu targets near the "--target-list" option.
-# The individual target constants are not documented here, for the
-# time being.
+#     The comprehensive enumeration of QEMU system emulation
+#     ("softmmu") targets.  Run "./configure --help" in the project
+#     root directory, and look for the \*-softmmu targets near the
+#     "--target-list" option.  The individual target constants are not
+#     documented here, for the time being.
 #
 # @rx: since 5.0
 #
@@ -382,9 +381,8 @@
 
 ##
 # @LostTickPolicy:
-#
-# Policy for handling lost ticks in timer devices.  Ticks end up
-# getting lost when, for example, the guest is paused.
+#     Policy for handling lost ticks in timer devices.  Ticks end up
+#     getting lost when, for example, the guest is paused.
 #
 # @discard: throw away the missed ticks and continue with future
 #     injection normally.  The guest OS will see the timer jump ahead
@@ -1926,9 +1924,8 @@
 
 ##
 # @CpuModelCompareResult:
-#
-# An enumeration of CPU model comparison results.  The result is
-# usually calculated using e.g. CPU features or CPU generations.
+#     An enumeration of CPU model comparison results.  The result is
+#     usually calculated using e.g. CPU features or CPU generations.
 #
 # @incompatible: If model A is incompatible to model B, model A is not
 #     guaranteed to run where model B runs and the other way around.
-- 
2.55.0

[PATCH 10/10] qapi: convert simple enum intros for block-core.json

[John Snow]

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

diff --git a/qapi/block-core.json b/qapi/block-core.json
index 84ef21736b8..5b1eaa8e786 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1357,10 +1357,9 @@
 
 ##
 # @BlockdevOnError:
-#
-# An enumeration of possible behaviors for errors on I/O operations.
-# The exact meaning depends on whether the I/O was initiated by a
-# guest or by a block job
+#     An enumeration of possible behaviors for errors on I/O
+#     operations.  The exact meaning depends on whether the I/O was
+#     initiated by a guest or by a block job
 #
 # @report: for guest operations, report the error to the guest; for
 #     jobs, cancel the job
-- 
2.55.0

Re: [PATCH 01/10] qapi: convert simple enum intros for vfio.json

[Cédric Le Goater]

On 9/9/26 06:16, John Snow wrote:
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>   qapi/vfio.json | 15 +++++++--------
>   1 file changed, 7 insertions(+), 8 deletions(-)
> 
> diff --git a/qapi/vfio.json b/qapi/vfio.json
> index 3d61fc38ecd..47fff8b979d 100644
> --- a/qapi/vfio.json
> +++ b/qapi/vfio.json
> @@ -10,14 +10,13 @@
>   
>   ##
>   # @QapiVfioMigrationState:
> -#
> -# An enumeration of the VFIO device migration states.  In addition to
> -# the regular states, there are prepare states (with 'prepare' suffix)
> -# which indicate that the device is just about to transition to the
> -# corresponding state.  Note that seeing a prepare state for state X
> -# doesn't guarantee that the next state will be X, as the state
> -# transition can fail and the device may transition to a different
> -# state instead.
> +#     An enumeration of the VFIO device migration states.  In addition
> +#     to the regular states, there are prepare states (with 'prepare'
> +#     suffix) which indicate that the device is just about to
> +#     transition to the corresponding state.  Note that seeing a
> +#     prepare state for state X doesn't guarantee that the next state
> +#     will be X, as the state transition can fail and the device may
> +#     transition to a different state instead.
>   #
>   # @stop: The device is stopped.
>   #

Reviewed-by: Cédric Le Goater <clg@redhat.com>

Thanks,

C.

Re: [PATCH 00/10] qapi: convert simple enum intro sections

[Markus Armbruster]

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

Re: [PATCH 05/10] qapi: convert simple enum intros for cypto.json

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/crypto.json | 18 +++++++++---------
>  1 file changed, 9 insertions(+), 9 deletions(-)
>
> diff --git a/qapi/crypto.json b/qapi/crypto.json
> index 5e395bc10c7..f85d1cebed3 100644
> --- a/qapi/crypto.json
> +++ b/qapi/crypto.json
> @@ -10,10 +10,10 @@
>  
>  ##
>  # @QCryptoTLSCredsEndpoint:
> -#
> -# The type of network endpoint that will be using the credentials.
> -# Most types of credential require different setup / structures
> -# depending on whether they will be used in a server versus a client.
> +#     The type of network endpoint that will be using the credentials.
> +#     Most types of credential require different setup / structures
> +#     depending on whether they will be used in a server versus a
> +#     client.
>  #
>  # @client: the network endpoint is acting as the client
>  #
> @@ -126,11 +126,11 @@
>  
>  ##
>  # @QCryptoIVGenAlgo:
> -#
> -# The supported algorithms for generating initialization vectors for
> -# full disk encryption.  The 'plain' generator should not be used for
> -# disks with sector numbers larger than 2^32, except where
> -# compatibility with pre-existing Linux dm-crypt volumes is required.
> +#     The supported algorithms for generating initialization vectors
> +#     for full disk encryption.  The 'plain' generator should not be
> +#     used for disks with sector numbers larger than 2^32, except
> +#     where compatibility with pre-existing Linux dm-crypt volumes is
> +#     required.

'plain' should be @plain, and this part of the text should probably go
below the member descriptions.  I spotted related issues in review of
your "[PATCH 12/12] qapi: convert simple command intros for
block-core.json" and "[PATCH 5/5] qapi: convert simple event intros for
block-core.json".  Same reaction: leave for later, note future work:

1. Add missing markup to argument / member / feature references.

2. Review and improve doc comments where the intro refers to arguments /
members / features.

>  #
>  # @plain: 64-bit sector number truncated to 32-bits
>  #