[PATCH 00/10] qapi: convert simple data struct/alternate intro sections

[PATCH 00/10] qapi: convert simple data struct/alternate intro sections

[John Snow]

Hello, this work converts "simple" intro sections for data struct
definitions (and one alternate) 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.)

"data struct" is another non-technical distinction that means a QAPI
struct that is not used as a branch, argument definition, or the basis
of another struct. In effect, it is only "data" and as a result, is
not *currently* a candidate to be inlined into any other definition.

Documentation that is to be "inlined"-- to be written into another
definition's documentation-- needs to ensure that the documentation
written in the "intro" segment is not crucial to understanding the
behavior of the individual members. The "intro" does not get inlined,
but the rest of the documentation does. These "data structs" as
isolated in this series currently are not eligible to be inlined. As
such, the precise distinction between intro and details for these
definitions is not presently as crucial - however, these structs may
become inlined in the future, so a closer eye is still warranted.

If you are a non-QAPI maintainer who has been CC'd on this series, you
may wish to review what information is being counted as the "intro"
(The indented paragraph) and keep in mind that in the future, this
text may not be visible to the end-user reading our QMP documentation
if this structure is utilized as the 'base' for another struct, used
as the arguments for a command or event, or used as branch of a
union. This series keeps it pretty simple, and every conversion herein
is being codified as "the intro", i.e. "not crucial to understanding
the behavior of the members of this struct".

John Snow (10):
  qapi: convert simple data struct intros for uefi.json
  qapi: convert simple data struct intros for misc-arm.json
  qapi: convert simple data struct intros for acpi.json
  qapi: convert simple data struct intros for run-state.json
  qapi: convert simple data struct intros for yank.json
  qapi: convert simple data struct intros for cxl.json
  qapi: convert simple data struct intros for virtio.json
  qapi: convert simple data struct intros for machine.json
  qapi: convert simple data struct intros for block-core.json
  qapi: convert simple alternate intros for common.json

 qapi/acpi.json       |  7 +++----
 qapi/block-core.json | 37 ++++++++++++++++---------------------
 qapi/common.json     |  7 +++----
 qapi/cxl.json        |  7 +++----
 qapi/machine.json    | 12 +++++-------
 qapi/misc-arm.json   |  9 ++++-----
 qapi/run-state.json  |  7 +++----
 qapi/uefi.json       |  5 ++---
 qapi/virtio.json     | 37 ++++++++++++++++---------------------
 qapi/yank.json       | 10 ++++------
 10 files changed, 59 insertions(+), 79 deletions(-)

-- 
2.55.0

[PATCH 01/10] qapi: convert simple data struct intros for uefi.json

[John Snow]

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

diff --git a/qapi/uefi.json b/qapi/uefi.json
index 86f33b234ba..cb2b5e1f531 100644
--- a/qapi/uefi.json
+++ b/qapi/uefi.json
@@ -17,9 +17,8 @@
 
 ##
 # @UefiVariable:
-#
-# UEFI Variable.  Check the UEFI specification for more detailed
-# information on the fields.
+#     UEFI Variable.  Check the UEFI specification for more detailed
+#     information on the fields.
 #
 # @guid: variable namespace GUID
 #
-- 
2.55.0

[PATCH 02/10] qapi: convert simple data struct intros for misc-arm.json

[John Snow]

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

diff --git a/qapi/misc-arm.json b/qapi/misc-arm.json
index a7b5498d2d3..8cb2ea77951 100644
--- a/qapi/misc-arm.json
+++ b/qapi/misc-arm.json
@@ -5,11 +5,10 @@
 
 ##
 # @GICCapability:
-#
-# The struct describes capability for a specific GIC (Generic
-# Interrupt Controller) version.  These bits are not only decided by
-# QEMU/KVM software version, but also decided by the hardware that the
-# program is running upon.
+#     The struct describes capability for a specific GIC (Generic
+#     Interrupt Controller) version.  These bits are not only decided
+#     by QEMU/KVM software version, but also decided by the hardware
+#     that the program is running upon.
 #
 # @version: version of GIC to be described.  Currently, only 2 and 3
 #     are supported.
-- 
2.55.0

[PATCH 03/10] qapi: convert simple data struct intros for acpi.json

[John Snow]

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

diff --git a/qapi/acpi.json b/qapi/acpi.json
index d2c59df30b2..291a04a7ea4 100644
--- a/qapi/acpi.json
+++ b/qapi/acpi.json
@@ -81,10 +81,9 @@
 
 ##
 # @ACPIOSTInfo:
-#
-# OSPM Status Indication for a device.  For description of possible
-# values of @source and @status fields see "_OST (OSPM Status
-# Indication)" chapter of ACPI5.0 spec.
+#     OSPM Status Indication for a device.  For description
+#     of possible values of @source and @status fields see "_OST (OSPM
+#     Status Indication)" chapter of ACPI5.0 spec.
 #
 # @device: device ID associated with slot
 #
-- 
2.55.0

[PATCH 04/10] qapi: convert simple data struct intros for run-state.json

[John Snow]

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

diff --git a/qapi/run-state.json b/qapi/run-state.json
index 2a968a6bc0b..703ca1bb5b9 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -585,10 +585,9 @@
 
 ##
 # @GuestPanicInformationTdx:
-#
-# TDX Guest panic information specific to TDX, as specified in the
-# "Guest-Hypervisor Communication Interface (GHCI) Specification",
-# section TDG.VP.VMCALL<ReportFatalError>.
+#     TDX Guest panic information specific to TDX, as specified in the
+#     "Guest-Hypervisor Communication Interface (GHCI) Specification",
+#     section TDG.VP.VMCALL<ReportFatalError>.
 #
 # @error-code: TD-specific error code
 #
-- 
2.55.0

[PATCH 05/10] qapi: convert simple data struct intros for yank.json

[John Snow]

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

diff --git a/qapi/yank.json b/qapi/yank.json
index 85a0c87719d..8ac4b773653 100644
--- a/qapi/yank.json
+++ b/qapi/yank.json
@@ -20,9 +20,8 @@
 
 ##
 # @YankInstanceBlockNode:
-#
-# Specifies which block graph node to yank.  See `YankInstance` for
-# more information.
+#     Specifies which block graph node to yank.  See `YankInstance`
+#     for more information.
 #
 # @node-name: the name of the block graph node
 #
@@ -33,9 +32,8 @@
 
 ##
 # @YankInstanceChardev:
-#
-# Specifies which character device to yank.  See `YankInstance` for
-# more information.
+#     Specifies which character device to yank.  See `YankInstance`
+#     for more information.
 #
 # @id: the chardev's ID
 #
-- 
2.55.0

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

[John Snow]

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

diff --git a/qapi/cxl.json b/qapi/cxl.json
index 82524f47cdf..631d4def2ac 100644
--- a/qapi/cxl.json
+++ b/qapi/cxl.json
@@ -441,10 +441,9 @@
 
 ##
 # @CxlDynamicCapacityExtent:
-#
-# A single dynamic capacity extent.  This is a contiguous allocation
-# of memory by Device Physical Address within a single Dynamic
-# Capacity Region on a CXL Type 3 Device.
+#     A single dynamic capacity extent.  This is a contiguous
+#     allocation of memory by Device Physical Address within a single
+#     Dynamic Capacity Region on a CXL Type 3 Device.
 #
 # @offset: The offset (in bytes) to the start of the region where the
 #     extent belongs to.
-- 
2.55.0

[PATCH 07/10] qapi: convert simple data struct intros for virtio.json

[John Snow]

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

diff --git a/qapi/virtio.json b/qapi/virtio.json
index 9aafc3a212f..0a4753cc343 100644
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -67,9 +67,8 @@
 
 ##
 # @VhostStatus:
-#
-# Information about a vhost device.  This information will only be
-# displayed if the vhost device is active.
+#     Information about a vhost device.  This information will only be
+#     displayed if the vhost device is active.
 #
 # @n-mem-sections: vhost_dev n_mem_sections
 #
@@ -110,10 +109,9 @@
 
 ##
 # @VirtioStatus:
-#
-# Full status of the virtio device with most VirtIODevice members.
-# Also includes the full status of the corresponding vhost device if
-# the vhost device is active.
+#     Full status of the virtio device with most VirtIODevice members.
+#     Also includes the full status of the corresponding vhost device
+#     if the vhost device is active.
 #
 # @name: VirtIODevice name
 #
@@ -473,9 +471,9 @@
 
 ##
 # @VirtioDeviceFeatures:
-#
-# The common fields that apply to most Virtio devices.  Some devices
-# may not have their own device-specific features (e.g. virtio-rng).
+#     The common fields that apply to most Virtio devices.  Some
+#     devices may not have their own device-specific features
+#     (e.g. virtio-rng).
 #
 # @transports: List of transport features of the virtio device
 #
@@ -754,8 +752,7 @@
 
 ##
 # @VirtioRingAvail:
-#
-# Information regarding the avail vring (a.k.a. driver area)
+#     Information regarding the avail vring (a.k.a. driver area)
 #
 # @flags: VRingAvail flags
 #
@@ -772,8 +769,7 @@
 
 ##
 # @VirtioRingUsed:
-#
-# Information regarding the used vring (a.k.a. device area)
+#     Information regarding the used vring (a.k.a. device area)
 #
 # @flags: VRingUsed flags
 #
@@ -938,13 +934,12 @@
 
 ##
 # @VirtIOGPUOutput:
-#
-# Describes configuration of a VirtIO GPU output.  If both @xres and
-# @yres are set, they take precedence over root virtio-gpu resolution
-# configuration and enable the corresponding output.  If none of @xres
-# and @yres are set, root virtio-gpu resolution configuration takes
-# precedence and only the first output is enabled.  Only setting one
-# of @xres or @yres is an error.
+#     Describes configuration of a VirtIO GPU output.  If both @xres
+#     and @yres are set, they take precedence over root virtio-gpu
+#     resolution configuration and enable the corresponding output.
+#     If none of @xres and @yres are set, root virtio-gpu resolution
+#     configuration takes precedence and only the first output is
+#     enabled.  Only setting one of @xres or @yres is an error.
 #
 # @name: the name of the output
 #
-- 
2.55.0

[PATCH 08/10] qapi: convert simple data struct intros for machine.json

[John Snow]

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

diff --git a/qapi/machine.json b/qapi/machine.json
index 942d35d7275..0516112f8e8 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -468,8 +468,7 @@
 
 ##
 # @NumaNodeOptions:
-#
-# Create a guest NUMA node.  (for OptsVisitor)
+#     Create a guest NUMA node.  (for OptsVisitor)
 #
 # @nodeid: NUMA node ID (increase by 1 from 0 if omitted)
 #
@@ -596,11 +595,10 @@
 
 ##
 # @NumaCpuOptions:
-#
-# Option "-numa cpu" overrides default cpu to node mapping.  It
-# accepts the same set of cpu properties as returned by
-# `query-hotpluggable-cpus[].props <query-hotpluggable-cpus>`, where
-# node-id could be used to override default node mapping.
+#     Option "-numa cpu" overrides default cpu to node mapping.  It
+#     accepts the same set of cpu properties as returned by
+#     `query-hotpluggable-cpus[].props <query-hotpluggable-cpus>`,
+#     where node-id could be used to override default node mapping.
 #
 # Since: 2.10
 ##
-- 
2.55.0

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

[John Snow]

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

diff --git a/qapi/block-core.json b/qapi/block-core.json
index 5b1eaa8e786..1ca147285e7 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -417,10 +417,9 @@
 
 ##
 # @BlockGraphInfo:
-#
-# Information about all nodes in a block (sub)graph in the form of
-# `BlockNodeInfo` data.  The base `BlockNodeInfo` struct contains the
-# information for the (sub)graph's root node.
+#     Information about all nodes in a block (sub)graph in the form of
+#     `BlockNodeInfo` data.  The base `BlockNodeInfo` struct contains
+#     the information for the (sub)graph's root node.
 #
 # @children: Array of links to this node's child nodes' information
 #
@@ -768,9 +767,8 @@
 
 ##
 # @BlockInfo:
-#
-# Block device information.  This structure describes a virtual device
-# and the backing device associated with it.
+#     Block device information.  This structure describes a virtual
+#     device and the backing device associated with it.
 #
 # @device: The device name associated with the virtual device.
 #
@@ -1607,9 +1605,8 @@
 
 ##
 # @BackupPerf:
-#
-# Optional parameters for backup.  These parameters don't affect
-# functionality, but may significantly affect performance.
+#     Optional parameters for backup.  These parameters don't affect
+#     functionality, but may significantly affect performance.
 #
 # @use-copy-range: Use copy offloading.  Default false.
 #
@@ -2705,11 +2702,10 @@
 
 ##
 # @ThrottleLimits:
-#
-# Limit parameters for throttling.  Since some limit combinations are
-# illegal, limits should always be set in one transaction.  All fields
-# are optional.  When setting limits, if a field is missing the
-# current value is not changed.
+#     Limit parameters for throttling.  Since some limit combinations
+#     are illegal, limits should always be set in one transaction.
+#     All fields are optional.  When setting limits, if a field is
+#     missing the current value is not changed.
 #
 # @iops-total: limit total I/O operations per second
 #
@@ -3492,12 +3488,11 @@
 
 ##
 # @Qcow2OverlapCheckFlags:
-#
-# Structure of flags for each metadata structure.  Setting a field to
-# 'true' makes QEMU guard that Qcow2 format structure against
-# unintended overwriting.  See Qcow2 format specification for detailed
-# information on these structures.  The default value is chosen
-# according to the template given.
+#     Structure of flags for each metadata structure.  Setting a field
+#     to 'true' makes QEMU guard that Qcow2 format structure against
+#     unintended overwriting.  See Qcow2 format specification for
+#     detailed information on these structures.  The default value is
+#     chosen according to the template given.
 #
 # @template: Specifies a template mode which can be adjusted using the
 #     other flags, defaults to 'cached'
-- 
2.55.0

[PATCH 10/10] qapi: convert simple alternate intros for common.json

[John Snow]

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

diff --git a/qapi/common.json b/qapi/common.json
index c1bbed21e7f..1352e664b23 100644
--- a/qapi/common.json
+++ b/qapi/common.json
@@ -52,10 +52,9 @@
 
 ##
 # @StrOrNull:
-#
-# This is a string value or the explicit lack of a string (null
-# pointer in C).  Intended for cases when 'optional absent' already
-# has a different meaning.
+#     This is a string value or the explicit lack of a string (null
+#     pointer in C).  Intended for cases when 'optional absent'
+#     already has a different meaning.
 #
 # @s: the string value
 #
-- 
2.55.0

Re: [PATCH 08/10] qapi: convert simple data struct intros for machine.json

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/machine.json | 12 +++++-------
>  1 file changed, 5 insertions(+), 7 deletions(-)
>
> diff --git a/qapi/machine.json b/qapi/machine.json
> index 942d35d7275..0516112f8e8 100644
> --- a/qapi/machine.json
> +++ b/qapi/machine.json
> @@ -468,8 +468,7 @@
>  
>  ##
>  # @NumaNodeOptions:
> -#
> -# Create a guest NUMA node.  (for OptsVisitor)
> +#     Create a guest NUMA node.  (for OptsVisitor)
>  #
>  # @nodeid: NUMA node ID (increase by 1 from 0 if omitted)
>  #

The (for OptsVisitor) part has become wrong.  I'll post a patch.

> @@ -596,11 +595,10 @@
>  
>  ##
>  # @NumaCpuOptions:
> -#
> -# Option "-numa cpu" overrides default cpu to node mapping.  It
> -# accepts the same set of cpu properties as returned by
> -# `query-hotpluggable-cpus[].props <query-hotpluggable-cpus>`, where
> -# node-id could be used to override default node mapping.
> +#     Option "-numa cpu" overrides default cpu to node mapping.  It
> +#     accepts the same set of cpu properties as returned by
> +#     `query-hotpluggable-cpus[].props <query-hotpluggable-cpus>`,
> +#     where node-id could be used to override default node mapping.
>  #
>  # Since: 2.10
>  ##

Re: [PATCH 03/10] qapi: convert simple data struct intros for acpi.json

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/acpi.json | 7 +++----
>  1 file changed, 3 insertions(+), 4 deletions(-)
>
> diff --git a/qapi/acpi.json b/qapi/acpi.json
> index d2c59df30b2..291a04a7ea4 100644
> --- a/qapi/acpi.json
> +++ b/qapi/acpi.json
> @@ -81,10 +81,9 @@
>  
>  ##
>  # @ACPIOSTInfo:
> -#
> -# OSPM Status Indication for a device.  For description of possible
> -# values of @source and @status fields see "_OST (OSPM Status
> -# Indication)" chapter of ACPI5.0 spec.
> +#     OSPM Status Indication for a device.  For description
> +#     of possible values of @source and @status fields see "_OST (OSPM
> +#     Status Indication)" chapter of ACPI5.0 spec.
>  #
>  # @device: device ID associated with slot
>  #

Another instance of "text that refers to arguments should probably go
below the argument descriptions", and again leaving for later.

Re: [PATCH 00/10] qapi: convert simple data struct/alternate intro sections

[Markus Armbruster]

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