[libvirt] [PATCH] tools: Document completer callback

[Michal Privoznik]

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
+ * need it). Any completer that requires connection must check
+ * whether connection is still alive.
+ *
+ * The @cmd then holds parsed user input which might be missing
+ * some arguments (user is still typing the command), but may
+ * already contain important data. For instance if completer
+ * needs domain XML it may inspect @cmd to find --domain. Using
+ * existing wrappers is advised. If @cmd does not contain all
+ * necessary bits, completer might return sensible defaults (i.e.
+ * 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
+ * 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
+ * state that the command accepts.
+ *
+ * Under no circumstances a completer can output anything. Nor to
+ * stdout nor to stderr. This would harm the user experience.
+ */
+
+
 char **
 virshDomainNameCompleter(vshControl *ctl,
                          const vshCmd *cmd ATTRIBUTE_UNUSED,
-- 
2.19.2