[gtksourceview/wip/search: 3/3] Doc: add a warning about unescape/escape utils functions

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

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

    Doc: add a warning about unescape/escape utils functions

 gtksourceview/gtksourceutils.c |   18 ++++++++++++++----
 1 files changed, 14 insertions(+), 4 deletions(-)
---
diff --git a/gtksourceview/gtksourceutils.c b/gtksourceview/gtksourceutils.c
index 9778196..5e13d26 100644
--- a/gtksourceview/gtksourceutils.c
+++ b/gtksourceview/gtksourceutils.c
@@ -36,8 +36,8 @@
  * @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 two characters: \n, \r, \t and \\.
+ * The purpose is to easily write those characters in a search entry.
  *
  * See also: gtk_source_utils_escape_search_text().
  *
@@ -124,11 +124,21 @@ 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 \.
+ *
+ * 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 cylces 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
  */