[imbus commit] r42 - trunk/imbus/src

[codesite...@google.com]

Author: motonobu
Date: Tue Nov 20 23:20:09 2007
New Revision: 42

Modified:
trunk/imbus/src/im_unicode.h
trunk/imbus/src/im_value.h

Log:
document update

Modified: trunk/imbus/src/im_unicode.h
==============================================================================
--- trunk/imbus/src/im_unicode.h (original)
+++ trunk/imbus/src/im_unicode.h Tue Nov 20 23:20:09 2007
@@ -22,6 +22,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,
+ * to a ucs4 character.
+ *
+ * If src doesn't point utf8 string, the behavior is unspecified.
+ *
*/
IMUniChar im_utf8_get_char (const IMChar *src);

@@ -52,7 +58,6 @@
* If src is longer than maxlen bytes and maxlen has positive value,
only first maxlen bytes are tested.
* 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.
*
@@ -101,6 +106,16 @@
/**
* @brief Validate a UTF16 string, return TRUE if valid, put pointer to
* first invalid char in **end
+ *
+ * The im_utf16_string_validate() function tests for any characters
encoded with utf16 at most maxlen bytes in the
+ * utf16 string to src points.
+ *
+ * If src is longer than maxlen bytes and maxlen has positive value,
only first maxlen bytes are tested.
+ * If maxlen indicates -1, whole string to src points are tested.
+ *
+ *
+ * If the str contains illegal utf16 characters and end is not a null
pointer, A pointer to the first illegal character is stored
+ * in the object pointed to by end.
*/
IMBool im_utf16_string_validate (const IMUInt16 *str,
IMInt maxlen,
@@ -109,6 +124,9 @@
/**
* @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.
* @param src_len the size of source buffer.
@@ -121,6 +139,9 @@

/**
* @brief Convert an ucs4 code to utf8 char sequence.
+ *
+ * The im_unichar_to_utf8() function shall convert one ucs4 characters
to utf8 string,
+ * specified by dest.
*
* @param dest destination buffer to store utf8 char sequence.
* @param src the ucs4 code to be converted.

Modified: trunk/imbus/src/im_value.h
==============================================================================
--- trunk/imbus/src/im_value.h (original)
+++ trunk/imbus/src/im_value.h Tue Nov 20 23:20:09 2007
@@ -35,6 +35,8 @@
/**
* @brief Create a new zero-filled IMValue object.
*
+ * The im_value_new() function shall allocate
+ *
* @return IMValue* a new IMValue object.
*/
IMValue* im_value_new ();
@@ -162,8 +164,11 @@
/**
* @brief Get the value type of a value holded in a IMValue object.
*
- * @param *value a IMValue object.
+ * The im_value_get_value_type() function shall return a type of the
data which the value contains.
+ * IM_TYPE_INVALID shall be returned if the value is a null pointer,
or is not a IMValue object instance,
+ * or has no data.
*
+ * @param *value a IMValue object.
* @return IMType a type name of the variant that has been filled into
the IMValue object.
*/
IMType im_value_get_value_type (const IMValue *value);
@@ -171,8 +176,12 @@
/**
* @brief Clear the value of a IMValue object.
*
- * @param *value a IMValue object.
+ * The im_value_clear() function shall clear the data stored in value.
*
+ * After calling im_value_clear() function, the data previously stored
in the value is clear and
+ * a type of data the value holds shall be IM_TYPE_INVALID.
+ *
+ * @param *value a IMValue object.
* @return The im_value_clear() function shall not return a value.
*/
void im_value_clear (IMValue *value);
@@ -426,7 +435,10 @@
*
* The im_value_get_c_string() function shall return a pointer to the
string contained in
* the IMValue object pointed by value.
- * A null pointer is returned if the datum contained in the IMValue
object is not string
+ * A null pointer is returned if the datum contained in the IMValue
object is not string, or
+ * the value argument is a null pointer.
+ *
+ * The string pointed to by the return value shall not be modified or freed.
*
* @param value a pointer to an IMValue object.
*