[gtksourceview] Improve doc of escape/unescape utils functions

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

commit 32148ca208be8d729a5e7574ec895fe599a21e55
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Fri Aug 23 22:18:12 2013 +0200

    Improve doc of escape/unescape utils functions

 gtksourceview/gtksourceutils.c |   23 +++++++++++++++++++----
 1 files changed, 19 insertions(+), 4 deletions(-)
---
diff --git a/gtksourceview/gtksourceutils.c b/gtksourceview/gtksourceutils.c
index 9778196..3956b7b 100644
--- a/gtksourceview/gtksourceutils.c
+++ b/gtksourceview/gtksourceutils.c
@@ -36,8 +36,11 @@
  * @text: the text to unescape.
  *
  * Use this function before gtk_source_search_settings_set_search_text(), to
- * unescape certain sequences of characters: \n, \r, \t and \\. The purpose is
- * to easily write those characters in a search entry.
+ * unescape the following sequences of characters: \n, \r, \t and \\.
+ * The purpose is to easily write those characters in a search entry.
+ *
+ * Note that unescaping the search text is not needed for regular expression
+ * searches.
  *
  * See also: gtk_source_utils_escape_search_text().
  *
@@ -124,11 +127,23 @@ gtk_source_utils_unescape_search_text (const gchar *text)
  * gtk_source_utils_escape_search_text:
  * @text: the text to escape.
  *
- * Use this function after gtk_source_search_settings_get_search_text(), to
- * escape certain characters: \n, \r, \t and \.
+ * Use this function to escape the following characters: \n, \r, \t and \.
+ *
+ * For a regular expression search, use g_regex_escape_string() instead.
+ *
+ * One possible use case is to take the #GtkTextBuffer's selection and put it in a
+ * search entry. The selection can contain tabulations, newlines, etc. So it's
+ * better to escape those special characters to better fit in the search entry.
  *
  * See also: gtk_source_utils_unescape_search_text().
  *
+ * <warning>
+ * The escape and unescape functions are not reciprocal! For example,
+ * escape (unescape (\)) = \\. So avoid cycles such as: search entry -> unescape
+ * -> search settings -> escape -> search entry. The original search entry text
+ * may be modified.
+ * </warning>
+ *
  * Returns: the escaped @text.
  * Since: 3.10
  */