[gtksourceview] Fix and improve documentation for the CompletionContext

[Sébastien Wilmet <swilmet src gnome org>]

commit eae4dfaa92eeb52112c11ceea684ee9f4609f168
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sat Mar 16 14:36:15 2013 +0100

    Fix and improve documentation for the CompletionContext

 gtksourceview/gtksourcecompletioncontext.c |   28 +++++++++++++++++-----------
 gtksourceview/gtksourcecompletioncontext.h |   13 ++++++++-----
 2 files changed, 25 insertions(+), 16 deletions(-)
---
diff --git a/gtksourceview/gtksourcecompletioncontext.c b/gtksourceview/gtksourcecompletioncontext.c
index 58d19f1..fddb099 100644
--- a/gtksourceview/gtksourcecompletioncontext.c
+++ b/gtksourceview/gtksourcecompletioncontext.c
@@ -24,21 +24,27 @@
  * @title: GtkSourceCompletionContext
  * @short_description: The context of a completion
  *
- * A completion context is created when a completion occurs. The completion can
- * be activated by several means, listed in #GtkSourceCompletionActivation.
+ * Initially, the completion window is hidden. For a completion to occur, it has
+ * to be activated. The different possible activations are listed in
+ * #GtkSourceCompletionActivation. When an activation occurs, a
+ * #GtkSourceCompletionContext object is created, and the eligible providers are
+ * asked to add proposals with gtk_source_completion_context_add_proposals().
  *
- * The completion can be activated by user request, i.e. when the user presses
- * <keycombo><keycap>Control</keycap><keycap>space</keycap></keycombo>, by default.
+ * If no proposals are added, the completion window remains hidden, and the
+ * context is destroyed.
  *
- * The completion can also be activated interactively, on each insertion or
- * deletion in the #GtkTextBuffer.
+ * On the other hand, if proposals are added, the completion window becomes
+ * visible, and the user can choose a proposal. If the user is not happy with
+ * the shown proposals, he or she can insert or delete characters, to modify the
+ * completion context and therefore hoping to see the proposal he or she wants.
+ * This means that when an insertion or deletion occurs in the #GtkTextBuffer
+ * when the completion window is visible, the eligible providers are again asked
+ * to add proposals. The #GtkSourceCompletionContext:activation remains the
+ * same in this case.
  *
  * A #GtkTextIter is associated with the context, this is where the completion
  * takes place. With this #GtkTextIter, you can get the associated
  * #GtkTextBuffer with gtk_text_iter_get_buffer().
- *
- * Once the context is created, the eligible providers are asked to add
- * proposals with gtk_source_completion_context_add_proposals().
  */
 
 #include "gtksourcecompletioncontext.h"
diff --git a/gtksourceview/gtksourcecompletioncontext.h b/gtksourceview/gtksourcecompletioncontext.h
index 520d96f..e0e0ce0 100644
--- a/gtksourceview/gtksourcecompletioncontext.h
+++ b/gtksourceview/gtksourcecompletioncontext.h
@@ -39,11 +39,14 @@ typedef struct _GtkSourceCompletionContextPrivate   GtkSourceCompletionContextPriv
 
 /**
  * GtkSourceCompletionActivation:
- * @GTK_SOURCE_COMPLETION_ACTIVATION_NONE: none.
- * @GTK_SOURCE_COMPLETION_ACTIVATION_INTERACTIVE: interactive activation
- * @GTK_SOURCE_COMPLETION_ACTIVATION_USER_REQUESTED: user requested activation
- * (e.g. through a keyboard accelerator from the view)
- **/
+ * @GTK_SOURCE_COMPLETION_ACTIVATION_NONE: None.
+ * @GTK_SOURCE_COMPLETION_ACTIVATION_INTERACTIVE: Interactive activation. By
+ * default, it occurs on each insertion in the #GtkTextBuffer. This can be
+ * blocked temporarily with gtk_source_completion_block_interactive().
+ * @GTK_SOURCE_COMPLETION_ACTIVATION_USER_REQUESTED: User requested activation.
+ * By default, it occurs when the user presses
+ * <keycombo><keycap>Control</keycap><keycap>space</keycap></keycombo>.
+ */
 typedef enum
 {
        GTK_SOURCE_COMPLETION_ACTIVATION_NONE = 0,