[glib/glib-2-22] [gutf8.c] Add a bit of documentation to UNICODE_VALID (cherry picked from commit 5047fd7f688dc0a3e4c

[Matthias Clasen <matthiasc src gnome org>]

commit 0e8a69e997cc33b2c6f52dd492755250221ff678
Author: Colin Walters <walters verbum org>
Date:   Fri Feb 19 16:06:22 2010 -0500

    [gutf8.c] Add a bit of documentation to UNICODE_VALID
    (cherry picked from commit 5047fd7f688dc0a3e4c148864f63961389bc83f9)

 glib/gutf8.c |   18 +++++++++++++++++-
 1 files changed, 17 insertions(+), 1 deletions(-)
---
diff --git a/glib/gutf8.c b/glib/gutf8.c
index ba13d0b..a7fbf6e 100644
--- a/glib/gutf8.c
+++ b/glib/gutf8.c
@@ -95,7 +95,23 @@
       (Result) <<= 6;							      \
       (Result) |= ((Chars)[(Count)] & 0x3f);				      \
     }
-
+    
+/**
+ * Check whether a Unicode (5.2) char is in a valid range.
+ *
+ * The first check comes from the Unicode guarantee to never encode
+ * a point above 0x0010ffff, since UTF-16 couldn't represent it.
+ * 
+ * The second check covers surrogate pairs (category Cs).
+ * 
+ * The last two checks cover "Noncharacter": defined as:
+ *   "A code point that is permanently reserved for
+ *    internal use, and that should never be interchanged. In
+ *    Unicode 3.1, these consist of the values U+nFFFE and U+nFFFF
+ *    (where n is from 0 to 10_16) and the values U+FDD0..U+FDEF."
+ *
+ * @param Char the character
+ */
 #define UNICODE_VALID(Char)                   \
     ((Char) < 0x110000 &&                     \
      (((Char) & 0xFFFFF800) != 0xD800) &&     \