1. Patchew
  2. QEMU
  3. [PATCH 00/18] QAPI: add cross-references to qapi docs
  4. View patch

[PATCH 17/18] qapi: add cross-references to yank.json

John Snow posted 18 patches 8 months ago
Maintainers: Eric Blake <eblake@redhat.com>, Markus Armbruster <armbru@redhat.com>, "Michael S. Tsirkin" <mst@redhat.com>, Igor Mammedov <imammedo@redhat.com>, Ani Sinha <anisinha@redhat.com>, "Daniel P. Berrangé" <berrange@redhat.com>, Kevin Wolf <kwolf@redhat.com>, Hanna Reitz <hreitz@redhat.com>, "Marc-André Lureau" <marcandre.lureau@redhat.com>, John Snow <jsnow@redhat.com>, Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru>, Eduardo Habkost <eduardo@habkost.net>, Marcel Apfelbaum <marcel.apfelbaum@gmail.com>, "Philippe Mathieu-Daudé" <philmd@linaro.org>, Yanan Wang <wangyanan55@huawei.com>, Zhao Liu <zhao1.liu@intel.com>, Peter Xu <peterx@redhat.com>, Fabiano Rosas <farosas@suse.de>, Jason Wang <jasowang@redhat.com>, Paolo Bonzini <pbonzini@redhat.com>, "Alex Bennée" <alex.bennee@linaro.org>, Lukas Straub <lukasstraub2@web.de>
There is a newer version of this series
[PATCH 17/18] qapi: add cross-references to yank.json
Posted by John Snow 8 months ago 
Signed-off-by: John Snow <jsnow@redhat.com>
---
 qapi/yank.json | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/qapi/yank.json b/qapi/yank.json
index 9bd8ecce27f..931d4b22d4b 100644
--- a/qapi/yank.json
+++ b/qapi/yank.json
@@ -9,7 +9,7 @@
 ##
 # @YankInstanceType:
 #
-# An enumeration of yank instance types.  See @YankInstance for more
+# An enumeration of `yank` instance types.  See `YankInstance` for more
 # information.
 #
 # Since: 6.0
@@ -20,7 +20,7 @@
 ##
 # @YankInstanceBlockNode:
 #
-# Specifies which block graph node to yank.  See @YankInstance for
+# Specifies which block graph node to `yank`.  See `YankInstance` for
 # more information.
 #
 # @node-name: the name of the block graph node
@@ -33,7 +33,7 @@
 ##
 # @YankInstanceChardev:
 #
-# Specifies which character device to yank.  See @YankInstance for
+# Specifies which character device to `yank`.  See `YankInstance` for
 # more information.
 #
 # @id: the chardev's ID
@@ -46,20 +46,20 @@
 ##
 # @YankInstance:
 #
-# A yank instance can be yanked with the @yank qmp command to recover
+# A `yank` instance can be yanked with the `yank` qmp command to recover
 # from a hanging QEMU.
 #
-# @type: yank instance type
+# @type: `yank` instance type
 #
-# Currently implemented yank instances:
+# Currently implemented `yank` instances:
 #
 # - nbd block device: Yanking it will shut down the connection to the
 #   nbd server without attempting to reconnect.
 # - socket chardev: Yanking it will shut down the connected socket.
 # - migration: Yanking it will shut down all migration connections.
-#   Unlike @migrate_cancel, it will not notify the migration process,
+#   Unlike `migrate_cancel`, it will not notify the migration process,
 #   so migration will go into @failed state, instead of @cancelled
-#   state.  @yank should be used to recover from hangs.
+#   state.  `yank` should be used to recover from hangs.
 #
 # Since: 6.0
 ##
@@ -74,7 +74,7 @@
 # @yank:
 #
 # Try to recover from hanging QEMU by yanking the specified instances.
-# See @YankInstance for more information.
+# See `YankInstance` for more information.
 #
 # @instances: the instances to be yanked
 #
@@ -100,7 +100,7 @@
 ##
 # @query-yank:
 #
-# Query yank instances.  See @YankInstance for more information.
+# Query `yank` instances.  See `YankInstance` for more information.
 #
 #
 # .. qmp-example::
-- 
2.48.1
Re: [PATCH 17/18] qapi: add cross-references to yank.json
Posted by Markus Armbruster 7 months, 1 week ago 
John Snow <jsnow@redhat.com> writes:

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/yank.json | 20 ++++++++++----------
>  1 file changed, 10 insertions(+), 10 deletions(-)
>
> diff --git a/qapi/yank.json b/qapi/yank.json
> index 9bd8ecce27f..931d4b22d4b 100644
> --- a/qapi/yank.json
> +++ b/qapi/yank.json
> @@ -9,7 +9,7 @@
>  ##
>  # @YankInstanceType:
>  #
> -# An enumeration of yank instance types.  See @YankInstance for more
> +# An enumeration of `yank` instance types.  See `YankInstance` for more

A yank instance is not an instance of the yank command.

I think most instances of "yank" should be left alone.  I'm going to
flag the ones that should be made links to the yank command.

>  # information.
>  #
>  # Since: 6.0
> @@ -20,7 +20,7 @@
>  ##
>  # @YankInstanceBlockNode:
>  #
> -# Specifies which block graph node to yank.  See @YankInstance for
> +# Specifies which block graph node to `yank`.  See `YankInstance` for
>  # more information.
>  #
>  # @node-name: the name of the block graph node
> @@ -33,7 +33,7 @@
>  ##
>  # @YankInstanceChardev:
>  #
> -# Specifies which character device to yank.  See @YankInstance for
> +# Specifies which character device to `yank`.  See `YankInstance` for
>  # more information.
>  #
>  # @id: the chardev's ID
> @@ -46,20 +46,20 @@
>  ##
>  # @YankInstance:
>  #
> -# A yank instance can be yanked with the @yank qmp command to recover
> +# A `yank` instance can be yanked with the `yank` qmp command to recover

Keep the second `yank`.

>  # from a hanging QEMU.
>  #
> -# @type: yank instance type
> +# @type: `yank` instance type
>  #
> -# Currently implemented yank instances:
> +# Currently implemented `yank` instances:
>  #
>  # - nbd block device: Yanking it will shut down the connection to the
>  #   nbd server without attempting to reconnect.
>  # - socket chardev: Yanking it will shut down the connected socket.
>  # - migration: Yanking it will shut down all migration connections.
> -#   Unlike @migrate_cancel, it will not notify the migration process,
> +#   Unlike `migrate_cancel`, it will not notify the migration process,
>  #   so migration will go into @failed state, instead of @cancelled
> -#   state.  @yank should be used to recover from hangs.
> +#   state.  `yank` should be used to recover from hangs.

Keep.

>  #
>  # Since: 6.0
>  ##
> @@ -74,7 +74,7 @@
>  # @yank:
>  #
>  # Try to recover from hanging QEMU by yanking the specified instances.
> -# See @YankInstance for more information.
> +# See `YankInstance` for more information.
>  #
>  # @instances: the instances to be yanked
>  #
> @@ -100,7 +100,7 @@
>  ##
>  # @query-yank:
>  #
> -# Query yank instances.  See @YankInstance for more information.
> +# Query `yank` instances.  See `YankInstance` for more information.
>  #
>  #
>  # .. qmp-example::
Re: [PATCH 17/18] qapi: add cross-references to yank.json
Posted by Lukas Straub 7 months, 3 weeks ago 
On Fri, 13 Jun 2025 16:36:19 -0400
John Snow <jsnow@redhat.com> wrote:

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/yank.json | 20 ++++++++++----------
>  1 file changed, 10 insertions(+), 10 deletions(-)
> 
> diff --git a/qapi/yank.json b/qapi/yank.json
> index 9bd8ecce27f..931d4b22d4b 100644
> --- a/qapi/yank.json
> +++ b/qapi/yank.json
> @@ -9,7 +9,7 @@
>  ##
>  # @YankInstanceType:
>  #
> -# An enumeration of yank instance types.  See @YankInstance for more
> +# An enumeration of `yank` instance types.  See `YankInstance` for more
>  # information.
>  #
>  # Since: 6.0
> @@ -20,7 +20,7 @@
>  ##
>  # @YankInstanceBlockNode:
>  #
> -# Specifies which block graph node to yank.  See @YankInstance for
> +# Specifies which block graph node to `yank`.  See `YankInstance` for
>  # more information.
>  #
>  # @node-name: the name of the block graph node
> @@ -33,7 +33,7 @@
>  ##
>  # @YankInstanceChardev:
>  #
> -# Specifies which character device to yank.  See @YankInstance for
> +# Specifies which character device to `yank`.  See `YankInstance` for
>  # more information.
>  #
>  # @id: the chardev's ID
> @@ -46,20 +46,20 @@
>  ##
>  # @YankInstance:
>  #
> -# A yank instance can be yanked with the @yank qmp command to recover
> +# A `yank` instance can be yanked with the `yank` qmp command to recover
>  # from a hanging QEMU.
>  #
> -# @type: yank instance type
> +# @type: `yank` instance type
>  #
> -# Currently implemented yank instances:
> +# Currently implemented `yank` instances:
>  #
>  # - nbd block device: Yanking it will shut down the connection to the
>  #   nbd server without attempting to reconnect.
>  # - socket chardev: Yanking it will shut down the connected socket.
>  # - migration: Yanking it will shut down all migration connections.
> -#   Unlike @migrate_cancel, it will not notify the migration process,
> +#   Unlike `migrate_cancel`, it will not notify the migration process,
>  #   so migration will go into @failed state, instead of @cancelled
> -#   state.  @yank should be used to recover from hangs.
> +#   state.  `yank` should be used to recover from hangs.
>  #
>  # Since: 6.0
>  ##
> @@ -74,7 +74,7 @@
>  # @yank:
>  #
>  # Try to recover from hanging QEMU by yanking the specified instances.
> -# See @YankInstance for more information.
> +# See `YankInstance` for more information.
>  #
>  # @instances: the instances to be yanked
>  #
> @@ -100,7 +100,7 @@
>  ##
>  # @query-yank:
>  #
> -# Query yank instances.  See @YankInstance for more information.
> +# Query `yank` instances.  See `YankInstance` for more information.
>  #
>  #
>  # .. qmp-example::

Acked-by: Lukas Straub <lukasstraub2@web.de>

Patchew 2.1-devel-b67e4c2

© 2016 - 2026 Red Hat, Inc.