[glib] Improve docs for g_utf16_to_utf8

[Matthias Clasen <matthiasc src gnome org>]

commit 442dadf3118cf3e2e9617461eb045f61483d58fc
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue Sep 29 20:39:39 2009 -0400

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

 glib/gutf8.c |   16 +++++++++++-----
 1 files changed, 11 insertions(+), 5 deletions(-)
---
diff --git a/glib/gutf8.c b/glib/gutf8.c
index 8225e48..ba13d0b 100644
--- 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