Clarify docs for g_uri_unescape_string() (#508773)

2008-01-15  Alexander Larsson  <alexl@redhat.com>

        * glib/gurifuncs.c:
	Clarify docs for g_uri_unescape_string() (#508773)

svn path=/trunk/; revision=6317

diff --git a/ChangeLog b/ChangeLog
index 826826e59991e41a4f67f0303480ecc5bae99f90..c3b720eedad7dab56b9e7cea4f95c33b85be1c43 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2008-01-15  Alexander Larsson  <alexl@redhat.com>
+
+        * glib/gurifuncs.c:
+       Clarify docs for g_uri_unescape_string() (#508773)
+
 2008-01-14  Dan Winship  <danw@gnome.org>
 
        * m4macros/glib-2.0.m4: Support gio in AM_PATH_GLIB_2_0 (#509465)

diff --git a/glib/gurifuncs.c b/glib/gurifuncs.c
index 0af480bf2e35a88e44066b420f0ea0436ddd468b..0a51a69aa2f342b53cdc0b3151630ea9d5f8c362 100644 (file)
--- a/glib/gurifuncs.c
+++ b/glib/gurifuncs.c
@@ -57,10 +57,16 @@ unescape_character (const char *scanner)
  * g_uri_unescape_segment:
  * @escaped_string: a string.
  * @escaped_string_end: a string.
- * @illegal_characters: a string of illegal characters not to be allowed.
+ * @illegal_characters: an optional string of illegal characters not to be allowed.
  * 
  * Unescapes a segment of an escaped string.
- * 
+ *
+ * If any of the characters in @illegal_characters or the character zero appears
+ * as an escaped character in @escaped_string then that is an error and %NULL
+ * will be returned. This is useful it you want to avoid for instance having a
+ * slash being expanded in an escaped path element, which might confuse pathname
+ * handling.
+ *
  * Returns: an unescaped version of @escaped_string or %NULL on error.
  * The returned string should be freed when no longer needed.
  *
@@ -123,10 +129,16 @@ g_uri_unescape_segment (const char *escaped_string,
 /**
  * g_uri_unescape_string:
  * @escaped_string: an escaped string to be unescaped.
- * @illegal_characters: a string of illegal characters not to be allowed.
+ * @illegal_characters: an optional string of illegal characters not to be allowed.
  * 
  * Unescapes a whole escaped string.
  * 
+ * If any of the characters in @illegal_characters or the character zero appears
+ * as an escaped character in @escaped_string then that is an error and %NULL
+ * will be returned. This is useful it you want to avoid for instance having a
+ * slash being expanded in an escaped path element, which might confuse pathname
+ * handling.
+ *
  * Returns: an unescaped version of @escaped_string. The returned string 
  * should be freed when no longer needed.
  *