[gtk+] doc: improve documentation of gtk_text_iter_inside_word()

[Matthias Clasen <matthiasc src gnome org>]

commit 22ce03fd9440f3b2bf6db78ef17e1e52222cdd2b
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Tue Apr 8 22:43:25 2014 +0200

    doc: improve documentation of gtk_text_iter_inside_word()
    
    There is a possible confusion with the sentence:
    "@iter is inside a natural-language word"
    
    The iter should be viewed here as the pointed character (i.e. on the
    right of the iter), not as a position between two characters.
    
    Instead of improving the documentation, another solution would have been
    to change the implementation so it is interpreted as an iter position
    inside a word, i.e. between two characters that are part of a
    natural-language word. But maybe some applications rely on the current
    implementation.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=727908

 gtk/gtktextiter.c |   15 +++++++++------
 1 files changed, 9 insertions(+), 6 deletions(-)
---
diff --git a/gtk/gtktextiter.c b/gtk/gtktextiter.c
index 5b91919..bb7fdb0 100644
--- a/gtk/gtktextiter.c
+++ b/gtk/gtktextiter.c
@@ -3402,12 +3402,15 @@ gtk_text_iter_ends_word (const GtkTextIter *iter)
 /**
  * gtk_text_iter_inside_word:
  * @iter: a #GtkTextIter
- * 
- * Determines whether @iter is inside a natural-language word (as
- * opposed to say inside some whitespace).  Word breaks are determined
- * by Pango and should be correct for nearly any language (if not, the
- * correct fix would be to the Pango word break algorithms).
- * 
+ *
+ * Determines whether the character pointed by @iter is part of a
+ * natural-language word (as opposed to say inside some whitespace).  Word
+ * breaks are determined by Pango and should be correct for nearly any language
+ * (if not, the correct fix would be to the Pango word break algorithms).
+ *
+ * Note that if gtk_text_iter_starts_word() returns %TRUE, then this function
+ * returns %TRUE too, since @iter points to the first character of the word.
+ *
  * Returns: %TRUE if @iter is inside a word
  **/
 gboolean