[imbus commit] r44 - trunk/imbus/src
codesite...@google.com
Date: Wed Nov 21 14:06:57 2007
New Revision: 44
Modified:
trunk/imbus/src/im_key_codes.h
trunk/imbus/src/im_unicode.h
Log:
document update
Modified: trunk/imbus/src/im_key_codes.h
==============================================================================
--- trunk/imbus/src/im_key_codes.h (original)
+++ trunk/imbus/src/im_key_codes.h Wed Nov 21 14:06:57 2007
@@ -1721,6 +1721,11 @@
/**
* @brief Get the name of a key value.
*
+ * The im_key_get_name() function
+ *
+ * If the specified keyval is not defined, im_key_get_name() returns NULL.
+ *
+ * @return The im_key_get_name() function returns
* @return A newly created IMString object,
* must be released by caller.
*/
@@ -1741,14 +1746,15 @@
* TODO: move it into libimbus-x11
*
* @keycode Specifies the KeyCode.
- * @returns X11 KeySym associated with keycode.
+ * @returns The im_key_code_to_x11keysym() function returns the Keysym
defined for the specified
+ * KeyCode. If no symbol is defined, im_key_code_to_x11keysym()
returns NoSymbol.
*/
IMUInt32 im_key_code_to_x11keysym (IMUInt32 keycode);
/**
* @brief Convert a X11 keysym to key code.
*
- * The im_key_code_from_x11keysym function returns the KeyCode
+ * The im_key_code_from_x11keysym() function shall convert
*
* TODO: move it into libimbus-x11
*
Modified: trunk/imbus/src/im_unicode.h
==============================================================================
--- trunk/imbus/src/im_unicode.h (original)
+++ trunk/imbus/src/im_unicode.h Wed Nov 21 14:06:57 2007
@@ -23,11 +23,12 @@
/**
* @brief Get an unicode char from an utf8 char sequence.
*
- * The im_utf8_get_char() function shall convert utf8 sequences that
src points to,
+ * The im_utf8_get_char() function shall convert the first character
from utf8 sequences that src points to,
* to a ucs4 character.
*
- * If src doesn't point utf8 string, the behavior is unspecified.
- *
+ * @return The im_utf8_get_char() function shall return ucs4 character
correspoinding to the src argument.
+ * If src is a null pointer or the character sequence pointed by src
does not form valid utf8 string,
+ * im_utf8_get_char() function shall return IM_UNICODE_CHAR_INVALID.
*/
IMUniChar im_utf8_get_char (const IMChar *src);
@@ -42,9 +43,9 @@
*
* In the case of src doesn't points utf8 string, the behavior is unspecified.
*
- * @param src the pointer to the utf8 string to be computed.
- * @param maxlen Maximum length of src, -1 means until 0.
- * @returns The im_utf8_strlen() function shall return the length of s
+ * @param src a pointer to the utf8 string to be computed.
+ * @param maxlen bytes used to compute the number of characters.
+ * @returns The im_utf8_strlen() function shall return the length of src.
*/
IMSize im_utf8_strlen (const IMChar *src,
IMInt maxlen);
@@ -55,15 +56,15 @@
* The im_utf8_string_validate() function tests for any characters
encoded with utf8 at most maxlen bytes in the
* utf8 string to src points.
*
- * If src is longer than maxlen bytes and maxlen has positive value,
only first maxlen bytes are tested.
+ * If src is longer than maxlen bytes and maxlen has positive value,
only first maxlen bytes are used to test .
* If maxlen indicates -1, whole string to src points are tested.
*
* If the str contains illegal utf8 characters and end is not a null
pointer, A pointer to the first illegal character is stored
* in the object pointed to by end.
*
- * @param str
- * @param maxlen
- * @returns The im_utf8_string_validate() function shall return TRUE
when str
+ * @param str the pointer to the utf8 string to be tested
+ * @param maxlen Maximum length of str to be tested
+ * @returns The im_utf8_string_validate() function shall return TRUE
If character sequences pointed to by str form a valid character in utf8 codeset.
*/
IMBool im_utf8_string_validate (const IMChar *str,
IMInt maxlen,
@@ -123,15 +124,18 @@
/**
* @brief Convert an utf8 char sequence to ucs4.
- *
- * The im_uniichar_from_utf8() function shall convert the sequence of
characters from utf8 string,
- * in the array specified by src, into a sequence for corresponding
characters in ucs4.
*
- * @param dest destination buffer to store the ucs4 code.
- * @param src source buffer contains the utf8 char sequence.
+ * The im_unichar_from_utf8() function shall convert the first
character from utf8 string pointed by src,
+ * into ucs4 character.
+ *
+ * @param dest a pointer to a variable that points to the first
available byte to store ucs4 character.
+ * @param src a pointer to a variable that points to the first
character in the input buffer.
* @param src_len the size of source buffer.
*
- * @return number of chars in src actually converted.
+ * @return The im_unichar_from_utf8() function shall update the
variables pointed to by the dest argument
+ * to reflect the extent of the conversion and return the number of
bytes of utf8 sequences consumed to perform the conversion.
+ * If a sequence of input bytes does not form a valid character in
utf8 codeset, im_unichar_from_utf8() function
+ * shall return 0 and the value pointed by dest shall be IM_UNICHAR_INVALID.
*/
IMSize im_unichar_from_utf8 (IMUniChar *dest,
const IMChar *src,
@@ -140,14 +144,16 @@
/**
* @brief Convert an ucs4 code to utf8 char sequence.
*
- * The im_unichar_to_utf8() function shall convert one ucs4 characters
to utf8 string,
+ * The im_unichar_to_utf8() function shall convert one ucs4 character
to utf8 string,
* specified by dest.
*
- * @param dest destination buffer to store utf8 char sequence.
- * @param src the ucs4 code to be converted.
+ * @param dest a pointer to a variable that points to the first
available byte to store utf8 string.
+ * @param src a ucs4 character to be converted
* @param dest_size the size of destination buffer.
*
- * @return the number of bytes actually written into dest.
+ * @return The im_unichar_to_utf8() function shall update the
variables pointed to by the dest argument
+ * to reflect the extent of the conversion and return the number of
bytes are written to the variables pointed to by the dest argument.
+ *
*/
IMSize im_unichar_to_utf8 (IMChar *dest,
IMUniChar src,
@@ -155,9 +161,12 @@
/**
* @brief Convert an utf16 char sequence to ucs4.
- *
- * @param dest destination buffer to store the ucs4 code.
- * @param src source buffer contains the utf16 char sequence.
+ *
+ * The im_unichar_from_utf16() function shall convert the first
character from utf16 string pointed by src,
+ * into ucs4 character.
+ *
+ * @param dest a pointer to a variable that points to the first
available byte to store ucs4 character.
+ * @param src a pointer to a variable that points to the first
character in the input buffer.
* @param src_len the size of source buffer.
*
* @return number of uint16 elements were actually converted.