[PATCH 0/5] qapi: qapi: convert simple event intro sections

[PATCH 0/5] qapi: qapi: convert simple event intro sections

[John Snow]

Hello, this work converts "simple" intro sections for event
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 event definitions cannot be inlined by any other definition, the
documentation text for events 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:
i.e. features, arguments, and return values will always be inserted
"after the intro".

John Snow (5):
  qapi: convert simple event intros for qdev.json
  qapi: convert simple event intros for net.json
  qapi: convert simple event intros for migration.json
  qapi: convert simple event intros for machine.json
  qapi: convert simple event intros for block-core.json

 qapi/block-core.json | 30 ++++++++++++++----------------
 qapi/machine.json    | 14 ++++++--------
 qapi/migration.json  |  9 ++++-----
 qapi/net.json        |  9 ++++-----
 qapi/qdev.json       |  9 ++++-----
 5 files changed, 32 insertions(+), 39 deletions(-)

-- 
2.55.0

[PATCH 1/5] qapi: convert simple event intros for qdev.json

[John Snow]

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

diff --git a/qapi/qdev.json b/qapi/qdev.json
index 2f951e5ef8d..a35321d2fd1 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -118,11 +118,10 @@
 
 ##
 # @DEVICE_DELETED:
-#
-# Emitted whenever the device removal completion is acknowledged by
-# the guest.  At this point, it's safe to reuse the specified device
-# ID.  Device removal can be initiated by the guest or by HMP/QMP
-# commands.
+#     Emitted whenever the device removal completion is acknowledged
+#     by the guest.  At this point, it's safe to reuse the specified
+#     device ID.  Device removal can be initiated by the guest or by
+#     HMP/QMP commands.
 #
 # @device: the device's ID if it has one
 #
-- 
2.55.0

[PATCH 2/5] qapi: convert simple event intros for net.json

[John Snow]

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

diff --git a/qapi/net.json b/qapi/net.json
index 4ea4bd1bc72..7aabd8b9260 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -1135,11 +1135,10 @@
 
 ##
 # @FAILOVER_NEGOTIATED:
-#
-# Emitted when VIRTIO_NET_F_STANDBY was enabled during feature
-# negotiation.  Failover primary devices which were hidden (not
-# hotplugged when requested) before will now be hotplugged by the
-# virtio-net standby device.
+#     Emitted when VIRTIO_NET_F_STANDBY was enabled during feature
+#     negotiation.  Failover primary devices which were hidden (not
+#     hotplugged when requested) before will now be hotplugged by the
+#     virtio-net standby device.
 #
 # @device-id: QEMU device id of the unplugged device
 #
-- 
2.55.0

[PATCH 3/5] qapi: convert simple event intros for migration.json

[John Snow]

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

diff --git a/qapi/migration.json b/qapi/migration.json
index e3beaea87bb..5fbd604f995 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -1708,11 +1708,10 @@
 
 ##
 # @UNPLUG_PRIMARY:
-#
-# Emitted from source side of a migration when migration state is
-# WAIT_UNPLUG.  Device was unplugged by guest operating system.
-# Device resources in QEMU are kept on standby to be able to re-plug
-# it in case of migration failure.
+#     Emitted from source side of a migration when migration state is
+#     WAIT_UNPLUG.  Device was unplugged by guest operating system.
+#     Device resources in QEMU are kept on standby to be able to
+#     re-plug it in case of migration failure.
 #
 # @device-id: QEMU device id of the unplugged device
 #
-- 
2.55.0

[PATCH 4/5] qapi: convert simple event intros for machine.json

[John Snow]

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

diff --git a/qapi/machine.json b/qapi/machine.json
index 9d709cb53e0..cf905afd4f1 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1125,10 +1125,9 @@
 
 ##
 # @BALLOON_CHANGE:
-#
-# Emitted when the guest changes the actual BALLOON level.  This value
-# is equivalent to the @actual field return by the `query-balloon`
-# command
+#     Emitted when the guest changes the actual BALLOON level.  This
+#     value is equivalent to the @actual field return by the
+#     `query-balloon` command
 #
 # @actual: the logical size of the VM in bytes.  Formula used:
 #     logical_vm_size = vm_ram_size - balloon_size
@@ -1556,10 +1555,9 @@
 
 ##
 # @MEMORY_DEVICE_SIZE_CHANGE:
-#
-# Emitted when the size of a memory device changes.  Only emitted for
-# memory devices that can actually change the size (e.g., virtio-mem
-# due to guest action).
+#     Emitted when the size of a memory device changes.  Only emitted
+#     for memory devices that can actually change the size (e.g.,
+#     virtio-mem due to guest action).
 #
 # @id: device's ID
 #
-- 
2.55.0

[PATCH 5/5] qapi: convert simple event intros for block-core.json

[John Snow]

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

diff --git a/qapi/block-core.json b/qapi/block-core.json
index 29f011dc209..84ef21736b8 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -5555,11 +5555,10 @@
 
 ##
 # @BLOCK_IMAGE_CORRUPTED:
-#
-# Emitted when a disk image is being marked corrupt.  The image can be
-# identified by its device or node name.  The 'device' field is always
-# present for compatibility reasons, but it can be empty ("") if the
-# image does not have a device name associated.
+#     Emitted when a disk image is being marked corrupt.  The image
+#     can be identified by its device or node name.  The 'device'
+#     field is always present for compatibility reasons, but it can be
+#     empty ("") if the image does not have a device name associated.
 #
 # @device: device name.  This is always present for compatibility
 #     reasons, but it can be empty ("") if the image does not have a
@@ -5788,11 +5787,10 @@
 
 ##
 # @BLOCK_JOB_PENDING:
-#
-# Emitted when a block job is awaiting explicit authorization to
-# finalize graph changes via `job-finalize`.  If this job is part of a
-# transaction, it will not emit this event until the transaction has
-# converged first.
+#     Emitted when a block job is awaiting explicit authorization to
+#     finalize graph changes via `job-finalize`.  If this job is part
+#     of a transaction, it will not emit this event until the
+#     transaction has converged first.
 #
 # @type: job type
 #
@@ -5833,12 +5831,12 @@
 
 ##
 # @BLOCK_WRITE_THRESHOLD:
-#
-# Emitted when writes on block device reaches or exceeds the
-# configured write threshold.  For thin-provisioned devices, this
-# means the device should be extended to avoid pausing for disk
-# exhaustion.  The event is one shot.  Once triggered, it needs to be
-# re-registered with another `block-set-write-threshold` command.
+#     Emitted when writes on block device reaches or exceeds the
+#     configured write threshold.  For thin-provisioned devices, this
+#     means the device should be extended to avoid pausing for disk
+#     exhaustion.  The event is one shot.  Once triggered, it needs to
+#     be re-registered with another `block-set-write-threshold`
+#     command.
 #
 # @node-name: graph node name on which the threshold was exceeded.
 #
-- 
2.55.0

Re: [PATCH 3/5] qapi: convert simple event intros for migration.json

[Fabiano Rosas]

John Snow <jsnow@redhat.com> writes:

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/migration.json | 9 ++++-----
>  1 file changed, 4 insertions(+), 5 deletions(-)
>
> diff --git a/qapi/migration.json b/qapi/migration.json
> index e3beaea87bb..5fbd604f995 100644
> --- a/qapi/migration.json
> +++ b/qapi/migration.json
> @@ -1708,11 +1708,10 @@
>  
>  ##
>  # @UNPLUG_PRIMARY:
> -#
> -# Emitted from source side of a migration when migration state is
> -# WAIT_UNPLUG.  Device was unplugged by guest operating system.
> -# Device resources in QEMU are kept on standby to be able to re-plug
> -# it in case of migration failure.
> +#     Emitted from source side of a migration when migration state is
> +#     WAIT_UNPLUG.  Device was unplugged by guest operating system.
> +#     Device resources in QEMU are kept on standby to be able to
> +#     re-plug it in case of migration failure.
>  #
>  # @device-id: QEMU device id of the unplugged device
>  #

Acked-by: Fabiano Rosas <farosas@suse.de>

Re: [PATCH 4/5] qapi: convert simple event intros for machine.json

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/machine.json | 14 ++++++--------
>  1 file changed, 6 insertions(+), 8 deletions(-)
>
> diff --git a/qapi/machine.json b/qapi/machine.json
> index 9d709cb53e0..cf905afd4f1 100644
> --- a/qapi/machine.json
> +++ b/qapi/machine.json
> @@ -1125,10 +1125,9 @@
>  
>  ##
>  # @BALLOON_CHANGE:
> -#
> -# Emitted when the guest changes the actual BALLOON level.  This value
> -# is equivalent to the @actual field return by the `query-balloon`
> -# command
> +#     Emitted when the guest changes the actual BALLOON level.  This
> +#     value is equivalent to the @actual field return by the
> +#     `query-balloon` command

@actual does not refer to the argument here, it refers to
query-balloon's result.  Harmless until we turn it into a link.  Not
fixable now, because we lack markup for such non-local references.

Yet another note of future work:

5. Implement markup for non-local argument / member / feature
references, and put it to use.

>  #
>  # @actual: the logical size of the VM in bytes.  Formula used:
>  #     logical_vm_size = vm_ram_size - balloon_size
> @@ -1556,10 +1555,9 @@
>  
>  ##
>  # @MEMORY_DEVICE_SIZE_CHANGE:
> -#
> -# Emitted when the size of a memory device changes.  Only emitted for
> -# memory devices that can actually change the size (e.g., virtio-mem
> -# due to guest action).
> +#     Emitted when the size of a memory device changes.  Only emitted
> +#     for memory devices that can actually change the size (e.g.,
> +#     virtio-mem due to guest action).
>  #
>  # @id: device's ID
>  #

Re: [PATCH 5/5] qapi: convert simple event intros for block-core.json

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/block-core.json | 30 ++++++++++++++----------------
>  1 file changed, 14 insertions(+), 16 deletions(-)
>
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index 29f011dc209..84ef21736b8 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -5555,11 +5555,10 @@
>  
>  ##
>  # @BLOCK_IMAGE_CORRUPTED:
> -#
> -# Emitted when a disk image is being marked corrupt.  The image can be
> -# identified by its device or node name.  The 'device' field is always
> -# present for compatibility reasons, but it can be empty ("") if the
> -# image does not have a device name associated.
> +#     Emitted when a disk image is being marked corrupt.  The image
> +#     can be identified by its device or node name.  The 'device'
> +#     field is always present for compatibility reasons, but it can be
> +#     empty ("") if the image does not have a device name associated.

'device' should be @device, and this part of the text should probably go
below the argument descriptions.  I spotted related issues in review of
your "[PATCH 12/12] qapi: convert simple command 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.

>  #
>  # @device: device name.  This is always present for compatibility
>  #     reasons, but it can be empty ("") if the image does not have a

[...]

Re: [PATCH 0/5] qapi: qapi: convert simple event intro sections

[Markus Armbruster]

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