diff --git a/ChangeLog b/ChangeLog
index f0204cb81..7aede896d 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2008-01-14  Alexander Larsson  <alexl@redhat.com>
+
+        * glib/gurifuncs.c:
+	Clarify docs for g_uri_escape_string (#508773)
+
 2008-01-12  Andre Klapper  <a9016009@gmx.de>
 
 	* configure.in: ALL_LINGUAS: remove line breaks from previous 
diff --git a/glib/gurifuncs.c b/glib/gurifuncs.c
index 8b728c001..0af480bf2 100644
--- a/glib/gurifuncs.c
+++ b/glib/gurifuncs.c
@@ -200,6 +200,13 @@ g_uri_get_scheme (const char  *uri)
  * @allow_utf8: %TRUE if the result can include UTF-8 characters.
  * 
  * Escapes a string for use in a URI.
+ *
+ * Normally all characters that are not "unreserved" (i.e. ASCII alphanumerical
+ * characters plus dash, dot, underscore and tilde) are escaped.
+ * But if you specify characters in @reserved_chars_allowed they are not
+ * escaped. This is useful for the "reserved" characters in the URI
+ * specification, since those are allowed unescaped in some portions of
+ * a URI. 
  * 
  * Returns: an escaped version of @unescaped. The returned string should be 
  * freed when no longer needed.