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@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@redhat.com> John