Improve docs for g_utf16_to_utf8

Document that g_utf16_to_utf8 does not validate the resulting
UTF-8 string. See bug 596314.

diff --git a/glib/gutf8.c b/glib/gutf8.c
index 8225e48..ba13d0b 100644 (file)
--- a/glib/gutf8.c
+++ b/glib/gutf8.c
@@ -1085,9 +1085,15 @@ g_ucs4_to_utf8 (const gunichar *str,
  *
  * Note that the input is expected to be already in native endianness,
  * an initial byte-order-mark character is not handled specially.
- * g_convert() can be used to convert a byte buffer of UTF-16 data of 
+ * g_convert() can be used to convert a byte buffer of UTF-16 data of
  * ambiguous endianess.
- * 
+ *
+ * Further note that this function does not validate the result
+ * string; it may e.g. include embedded NUL characters. The only
+ * validation done by this function is to ensure that the input can
+ * be correctly interpreted as UTF-16, i.e. it doesn't contain
+ * things unpaired surrogates.
+ *
  * Return value: a pointer to a newly allocated UTF-8 string.
  *               This value must be freed with g_free(). If an
  *               error occurs, %NULL will be returned and
@@ -1095,9 +1101,9 @@ g_ucs4_to_utf8 (const gunichar *str,
  **/
 gchar *
 g_utf16_to_utf8 (const gunichar2  *str,
-                glong             len,              
-                glong            *items_read,       
-                glong            *items_written,    
+                glong             len,
+                glong            *items_read,
+                glong            *items_written,
                 GError          **error)
 {
   /* This function and g_utf16_to_ucs4 are almost exactly identical - The lines that differ