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

[Markus Armbruster <armbru@redhat.com>]

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