Re: [PATCH 06/18] qapi: add cross-references to job.json

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/job.json | 73 ++++++++++++++++++++++++++-------------------------
>  1 file changed, 37 insertions(+), 36 deletions(-)
>
> diff --git a/qapi/job.json b/qapi/job.json
> index c1ddae9c0fe..ffeac7989dd 100644
> --- a/qapi/job.json
> +++ b/qapi/job.json

[...]

> @@ -59,13 +59,14 @@
>  # @standby: The job is ready, but paused.  This is nearly identical to
>  #     @paused.  The job may return to @ready or otherwise be canceled.
>  #
> -# @waiting: The job is waiting for other jobs in the transaction to
> -#     converge to the waiting state.  This status will likely not be
> -#     visible for the last job in a transaction.
> +# @waiting: The job is waiting for other jobs in the
> +#     :qapi:cmd:`transaction` to converge to the waiting state.  This
> +#     status will likely not be visible for the last job in a
> +#     transaction.

Let's punt on this one as per review of PATCH 03.

>  #
>  # @pending: The job has finished its work, but has finalization steps
>  #     that it needs to make prior to completing.  These changes will
> -#     require manual intervention via @job-finalize if auto-finalize
> +#     require manual intervention via `job-finalize` if auto-finalize
>  #     was set to false.  These pending changes may still fail.
>  #
>  # @aborting: The job is in the process of being aborted, and will

[...]

> @@ -236,10 +237,10 @@
>  ##
>  # @job-finalize:
>  #
> -# Instructs all jobs in a transaction (or a single job if it is not
> -# part of any transaction) to finalize any graph changes and do any
> -# necessary cleanup.  This command requires that all involved jobs are
> -# in the PENDING state.
> +# Instructs all jobs in a :qapi:cmd:`transaction` (or a single job if it
> +# is not part of any transaction) to finalize any graph changes and do
> +# any necessary cleanup.  This command requires that all involved jobs
> +# are in the PENDING state.
>  #
>  # For jobs in a transaction, instructing one job to finalize will
>  # force ALL jobs in the transaction to finalize, so it is only
> @@ -248,7 +249,7 @@
>  # The command is applicable only to jobs which have @auto-finalize option
>  # and only when this option is set to false.
>  #
> -# @id: The identifier of any job in the transaction, or of a job that
> +# @id: The identifier of any job in the :qapi:cmd:`transaction`, or of a job that
>  #     is not part of any transaction.
>  #
>  # Since: 3.0

Likewise.