Re: [Qemu-devel] [PATCH v3 12/12] Dump: enhance the documentations.

[Eric Blake <eblake@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 2437 bytes --]

On 11/30/2015 04:32 AM, Peter Xu wrote:
> Add more documents to mention about "query-dump" and DUMP_COMPLETED
> events.
> 
> Signed-off-by: Peter Xu <peterx@redhat.com>
> ---
>  qapi-schema.json | 7 +++++--
>  qmp-commands.hx  | 4 +++-
>  2 files changed, 8 insertions(+), 3 deletions(-)

Why not squash this in to the patch that introduces the options?  No
need to have churn within the series by tweaking the documentation more
than once.

> 
> diff --git a/qapi-schema.json b/qapi-schema.json
> index 577c381..ce4acb2 100644
> --- a/qapi-schema.json
> +++ b/qapi-schema.json
> @@ -2115,8 +2115,11 @@
>  #            2. fd: the protocol starts with "fd:", and the following string
>  #               is the fd's name.
>  #
> -# @detach: #optional if true, QMP will return immediately rather than
> -#          waiting dump to be finished (since 2.6).
> +# @detach: #optional if true, QMP will return immediately rather
> +#          than waiting dump to be finished. If this is specified,
> +#          user could later use "query-dump" to check latest dump
> +#          status. When dump finishes, one event DUMP_COMPLETED will

s/one event DUMP_COMPLETED/a DUMP_COMPLETED event/

> +#          be sent to the user to notify the completion (since 2.6).

s/to the user to notify the completion//

>  #
>  # @begin: #optional if specified, the starting physical address.
>  #
> diff --git a/qmp-commands.hx b/qmp-commands.hx
> index ac6d2da..cd097d4 100644
> --- a/qmp-commands.hx
> +++ b/qmp-commands.hx
> @@ -858,7 +858,9 @@ Arguments:
>  - "protocol": destination file(started with "file:") or destination file
>                descriptor (started with "fd:") (json-string)
>  - "detach": if specificed, command will return immediately, without waiting
> -            for dump to be finished (json-bool)
> +            for dump to be finished. After command return, user
> +            could query for latest dump status using "query-dump". When dump
> +            finishes, an event DUMP_COMPLETED will be sent (json-bool)

Awkward.  How about:

- "detach": if specified, the command will return immediately rather
than waiting for the dump completion. The user can track progress with
"query-dump", and a DUMP_COMPLETED event will occur at the end. (json-bool)

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]