Re: [PATCH] hmp/migration: Fix documents for "migrate" command

[Markus Armbruster <armbru@redhat.com>]

Peter Xu <peterx@redhat.com> writes:

> Peter missed the Sphinx HMP document for the "resume/-r" flag in commit
> 7a4da28b26 ("qmp: hmp: add migrate "resume" option").  Add it.  Avoid
> adding a Fixes to make life easier for the stable maintainer.

I'm curious: how does not adding Fixes: make life easier?

> When at it, slightly cleanup the lines, move "detach/-d" to a separate
> section rather than appending it at the end of the command description.
>
> Cc: Dr. David Alan Gilbert <dave@treblig.org>
> Cc: Fabiano Rosas <farosas@suse.de>
> Cc: Markus Armbruster <armbru@redhat.com>
> Signed-off-by: Peter Xu <peterx@redhat.com>
> ---
>
> Based-on: <20240430142737.29066-1-farosas@suse.de>
> ("[PATCH v3 0/6] migration removals & deprecations")
> ---
>  hmp-commands.hx | 9 +++++++--
>  1 file changed, 7 insertions(+), 2 deletions(-)
>
> diff --git a/hmp-commands.hx b/hmp-commands.hx
> index ebca2cdced..484a8a1c3a 100644
> --- a/hmp-commands.hx
> +++ b/hmp-commands.hx
> @@ -918,8 +918,13 @@ ERST
       {
           .name       = "migrate",
           .args_type  = "detach:-d,blk:-b,inc:-i,resume:-r,uri:s",
           .params     = "[-d] [-b] [-i] [-r] uri",
           .help       = "migrate to URI (using -d to not wait for completion)"
                         "\n\t\t\t -b for migration without shared storage with"
                         " full copy of disk\n\t\t\t -i for migration without "
                         "shared storage with incremental copy of disk "
                         "(base image shared between src and destination)"
                         "\n\t\t\t -r to resume a paused migration",
           .cmd        = hmp_migrate,
       },
>  
>  
>  SRST
> -``migrate [-d]`` *uri*
> -  Migrate to *uri* (using -d to not wait for completion).
> +``migrate [-d] [-r]`` *uri*
> +  Migrate the current VM to *uri*.

Could there be any other VM than the current one?  Scratch "current"?

> +
> +  ``-d``
> +    Run this command asynchronously, so that the command doesn't wait for completion.

What is run asynchronously, and what isn't waiting?  These are two
different entities, aren't they?  Calling them "this command" and "the
command" is confusing :)

Perhaps

       Start the migration process, but do not wait for its completion.

Maybe add a hint on how to wait or poll for completion?

> +  ``-r``
> +    Resume a paused postcopy migration.

.help doesn't have "postcopy".  Should it?

>  ERST
>  
>      {