[libvirt] [PATCH] tools: Document completer callback

[John Ferlan]

On 1/22/19 7:15 AM, Michal Privoznik wrote:
> Strictly speaking, this should go near vshCompleter typedef
> declaration. However, I find it more useful near actual completer
> implementations.
> 
> Signed-off-by: Michal Privoznik <mprivozn at redhat.com>
> ---
>  tools/virsh-completer.c | 32 ++++++++++++++++++++++++++++++++
>  1 file changed, 32 insertions(+)
> 
> diff --git a/tools/virsh-completer.c b/tools/virsh-completer.c
> index cfbfeae328..7a637a0cfa 100644
> --- a/tools/virsh-completer.c
> +++ b/tools/virsh-completer.c
> @@ -35,6 +35,38 @@
>  #include "virxml.h"
>  
>  
> +/**
> + * A completer callback is a function that accepts three arguments:
> + *
> + *   @ctl: virsh control structure
> + *   @cmd: parsed input
> + *   @flags: optional flags to alter completer's behaviour
> + *
> + * The @ctl contains connection to the daemon (should completer
                                                        ^^^
should the

> + * need it). Any completer that requires connection must check
                                          ^^^^
requires a

> + * whether connection is still alive.
            ^^^
the connection

> + *
> + * The @cmd then holds parsed user input which might be missing
The @cmd contains parsed

> + * some arguments (user is still typing the command), but may
                     ^^^
(if user

> + * already contain important data. For instance if completer
                                                    ^^^
if the

> + * needs domain XML it may inspect @cmd to find --domain. Using
                     ^^
XML,

> + * existing wrappers is advised. If @cmd does not contain all
> + * necessary bits, completer might return sensible defaults (i.e.
                     ^^^
the completer

> + * generic values not tailored to specific use case) or return
> + * NULL (i.e. no strings are offered to the user for completion).
> + *
> + * The @flags then contain .completer_flags value defined for

The @flags contains a

> + * each use or 0 if no .completer_flags were specified. If a
> + * completer is generic enough @flags can be used to alter it's
> + * behaviour. For instance, a completer to fetch names of domains
> + * can use @flags to return names of only domains in particular
                                                      ^^^
in a particular

> + * state that the command accepts.
> + *
> + * Under no circumstances a completer can output anything. Nor to

Under no circumstances should a completer output anything. Neither to
stdout nor to stderr.

> + * stdout nor to stderr. This would harm the user experience.
> + */
> +
> +
>  char **
>  virshDomainNameCompleter(vshControl *ctl,
>                           const vshCmd *cmd ATTRIBUTE_UNUSED,
> 

Hope the edits make sense ...

Reviewed-by: John Ferlan <jferlan at redhat.com>

John