[gtksourceview] Completion doc: more details about proposal activation

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

commit bd3db0464d2833992cca2c41f7bfd684d75305a5
Author: SÃbastien Wilmet <swilmet src gnome org>
Date:   Sun Apr 22 18:30:00 2012 +0200

    Completion doc: more details about proposal activation
    
    The documentation about
    gtk_source_completion_provider_activate_proposal() was wrong, it's not
    the label of the proposal which is inserted in the buffer, it's the text
    of the proposal.
    
    The documentation is based on the following functions.
    
    In gtksourcecompletion.c:
    - activate_current_proposal()
    
    In gtksourcecompletionutils.c:
    - gtk_source_completion_utils_get_word_iter()
    - gtk_source_completion_utils_is_separator()

 gtksourceview/gtksourcecompletionproposal.c |    4 +++-
 gtksourceview/gtksourcecompletionprovider.c |   15 +++++++++++++--
 2 files changed, 16 insertions(+), 3 deletions(-)
---
diff --git a/gtksourceview/gtksourcecompletionproposal.c b/gtksourceview/gtksourcecompletionproposal.c
index 1820b2a..d795937 100644
--- a/gtksourceview/gtksourcecompletionproposal.c
+++ b/gtksourceview/gtksourcecompletionproposal.c
@@ -174,7 +174,9 @@ gtk_source_completion_proposal_get_markup (GtkSourceCompletionProposal *proposal
  * Gets the text of @proposal. The text that is inserted into
  * the text buffer when the proposal is activated by the default activation.
  * You are free to implement a custom activation handler in the provider and
- * not implement this function. The returned string must be freed with g_free().
+ * not implement this function. For more information, see
+ * gtk_source_completion_provider_activate_proposal(). The returned string must
+ * be freed with g_free().
  *
  * Returns: a new string containing the text of @proposal.
  */
diff --git a/gtksourceview/gtksourcecompletionprovider.c b/gtksourceview/gtksourcecompletionprovider.c
index ab4609c..5217aa2 100644
--- a/gtksourceview/gtksourcecompletionprovider.c
+++ b/gtksourceview/gtksourcecompletionprovider.c
@@ -283,8 +283,12 @@ gtk_source_completion_provider_update_info (GtkSourceCompletionProvider *provide
  * completion window accordingly when a proposal is selected in the completion
  * window.
  *
+ * When the @proposal is activated, the default handler uses @iter as the start
+ * of the word to replace. See
+ * gtk_source_completion_provider_activate_proposal() for more information.
+ *
  * Returns: %TRUE if @iter was set for @proposal, %FALSE otherwise.
- **/
+ */
 gboolean
 gtk_source_completion_provider_get_start_iter (GtkSourceCompletionProvider *provider,
                                                GtkSourceCompletionContext  *context,
@@ -310,7 +314,14 @@ gtk_source_completion_provider_get_start_iter (GtkSourceCompletionProvider *prov
  *
  * Activate @proposal at @iter. When this functions returns %FALSE, the default
  * activation of @proposal will take place which replaces the word at @iter
- * with the label of @proposal.
+ * with the text of @proposal (see gtk_source_completion_proposal_get_text()).
+ *
+ * Here is how the default activation selects the boundaries of the word to
+ * replace. The end of the word is @iter. For the start of the word, it depends
+ * on wheter a start iter is defined for @proposal (see
+ * gtk_source_completion_provider_get_start_iter()). If a start iter is defined,
+ * the start of the word is the start iter. Else, the word (as long as possible)
+ * will contain only alphanumerical and the "_" characters.
  *
  * Returns: %TRUE to indicate that the proposal activation has been handled,
  *          %FALSE otherwise.