- * Returns: The number of characters after conversion. If this is greater than
- * @len, the characters in the array will be safely truncated at len, but the
- * true count will be returned. (The contents of the buffer after the returned
- * count are undefined.)
+ * The functions return the number of characters after conversion. If this is
+ * greater than @len, the characters in the array will be safely truncated at
+ * @len, but the true count will be returned. (The contents of the buffer after
+ * the returned count are undefined.)
+ *
+ * The <code>lower_case</code> and <code>upper_case</code> functions do what
+ * you'd expect: they convert every character in the buffer (the first @numchars
+ * of them) to its upper or lower-case equivalent, if there is such a thing.
+ *
+ * See the Unicode spec (chapter 3.13, chapter 4.2, etc) for the exact
+ * definitions of upper, lower, and title-case mapping.
+ *
+ * <note><para>
+ * Unicode has some strange case cases. For example, a combined character
+ * that looks like <quote>ss</quote> might properly be upper-cased into
+ * <emphasis>two</emphasis> characters <quote>S</quote>. Title-casing is even
+ * stranger; <quote>ss</quote> (at the beginning of a word) might be
+ * title-cased into a different combined character that looks like
+ * <quote>Ss</quote>. The glk_buffer_to_title_case_uni() function is actually
+ * title-casing the first character of the buffer. If it makes a difference.
+ * </para></note>
+ *
+ * Returns: The number of characters after conversion.