[gtksourceview] Completion: better document the proposal text alignment

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

commit e4484e4f8ffa7ed8f46c4c84c1b207554184dc61
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Thu Aug 29 14:05:17 2013 +0200

    Completion: better document the proposal text alignment

 gtksourceview/gtksourcecompletion.c         |    3 ---
 gtksourceview/gtksourcecompletionprovider.c |   10 +++++++---
 2 files changed, 7 insertions(+), 6 deletions(-)
---
diff --git a/gtksourceview/gtksourcecompletion.c b/gtksourceview/gtksourcecompletion.c
index 75ced9b..bed43ec 100644
--- a/gtksourceview/gtksourcecompletion.c
+++ b/gtksourceview/gtksourcecompletion.c
@@ -60,9 +60,6 @@
  * displayed in a #GtkSourceCompletionInfo window, which appears when
  * the "Details" button is clicked.
  *
- * The #GtkSourceCompletionInfo window for proposals will try to align the
- * proposal text with the #GtkSourceView<!-- -->'s cursor.
- *
  * A #GtkSourceCompletionInfo window can also be used to display
  * calltips. When no proposals are available, it can be useful to
  * display extra information like a function's prototype (number of
diff --git a/gtksourceview/gtksourcecompletionprovider.c b/gtksourceview/gtksourcecompletionprovider.c
index a44ee88..6b537ad 100644
--- a/gtksourceview/gtksourcecompletionprovider.c
+++ b/gtksourceview/gtksourcecompletionprovider.c
@@ -293,9 +293,13 @@ gtk_source_completion_provider_update_info (GtkSourceCompletionProvider *provide
  * @iter: a #GtkTextIter.
  *
  * Get the #GtkTextIter at which the completion for @proposal starts. When
- * implemented, the completion can use this information to position the
- * completion window accordingly when a proposal is selected in the completion
- * window.
+ * implemented, this information is used to position the completion window
+ * accordingly when a proposal is selected in the completion window. The
+ * @proposal text inside the completion window is aligned on @iter.
+ *
+ * If this function is not implemented, the word boundary is taken to position
+ * the completion window. See gtk_source_completion_provider_activate_proposal()
+ * for an explanation on the word boundaries.
  *
  * When the @proposal is activated, the default handler uses @iter as the start
  * of the word to replace. See