[gtksourceview/wip/chergert/vim] add some documentation

[Christian Hergert <chergert src gnome org>]

commit 6ed6c34004614a27b24cbf82923c8e4a35245d03
Author: Christian Hergert <chergert redhat com>
Date:   Thu Nov 11 17:06:23 2021 -0800

    add some documentation

 gtksourceview/gtksourcevimimcontext.c | 34 +++++++++++++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)
---
diff --git a/gtksourceview/gtksourcevimimcontext.c b/gtksourceview/gtksourcevimimcontext.c
index 141cd560..c7b26fdb 100644
--- a/gtksourceview/gtksourcevimimcontext.c
+++ b/gtksourceview/gtksourcevimimcontext.c
@@ -31,7 +31,39 @@
 /**
  * SECTION:vimimcontext
  * @title: GtkSourceVimIMContext
- * @short_description: VIM emulation
+ * @short_description: Vim emulation
+ *
+ * The #GtkSourceVimIMContext is a #GtkIMContext implementation that can
+ * be used to provide Vim-like editing controls within a #GtkSourceView.
+ *
+ * The #GtkSourceViMIMContext will process incoming #GdkKeyEvent as the
+ * user types. It should be used in conjunction with a #GtkEventControllerKey.
+ *
+ * It is recommended that applications display the contents of
+ * #GtkSourceVimIMContext:command-bar-text and
+ * #GtkSourceVimIMContext:command-text to the user as they represent the
+ * command-bar and current command preview found in Vim.
+ *
+ * #GtkSourceVimIMContext attempts to work with additional #GtkIMContext
+ * implementations such as IBus by querying the #GtkTextView before processing
+ * the command in states which support it (notably Insert and Replace modes).
+ *
+ * <informalexample><programlisting>
+ *  GtkEventController *key;
+ *  GtkSourceView *view;
+ *  GtkIMContext *im_context;
+ *
+ *  view = gtk_source_view_new ();
+ *  im_context = gtk_source_vim_im_context_new ();
+ *  key = gtk_event_controller_key_new ();
+ *
+ *  gtk_event_controller_key_set_im_context (GTK_EVENT_CONTROLLER_KEY (key), im_context);
+ *  gtk_event_controller_set_propagation_phase (key, GTK_PHASE_CAPTURE);
+ *  gtk_widget_add_controller (GTK_WIDGET (view), key);
+ *
+ *  g_object_bind_property (im_context, "command-bar-text", command_bar_label, "label", 0);
+ *  g_object_bind_property (im_context, "command-text", command_label, "label", 0);
+ * </programlisting></informalexample>
  *
  * Since: 5.4
  */