[imbus commit] r37 - trunk/imbus/src
codesite...@google.com
Date: Mon Nov 19 05:59:17 2007
New Revision: 37
Modified:
trunk/imbus/src/im_unicode.h
trunk/imbus/src/im_utilities.h
trunk/imbus/src/im_value.h
Log:
update doc
Modified: trunk/imbus/src/im_unicode.h
==============================================================================
--- trunk/imbus/src/im_unicode.h (original)
+++ trunk/imbus/src/im_unicode.h Mon Nov 19 05:59:17 2007
@@ -44,8 +44,21 @@
IMInt maxlen);
/**
- * @brief Validate a UTF8 string, return TRUE if valid, put pointer to
- * first invalid char in **end
+ * @brief validate a utf8 string.
+ *
+ * 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 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
*/
IMBool im_utf8_string_validate (const IMChar *str,
IMInt maxlen,
@@ -69,11 +82,18 @@
/**
* @brief Return how many unicode chars in a given utf16 sequence.
*
- * The im_utf8_strlen() function shall compute the number of
characters in the string
+ * The im_utf16_strlen() function shall compute the number of
characters at most maxlen bytes in the utf16 string
* to src points, not including the terminating null byte.
*
+ * If src is longer than maxlen bytes, and maxlen has positive value,
only first maxlen bytes are used to compute the number of
+ * characters.
+ * If maxlen indicates -1, whole utf16 string to src points are computed.
+ *
+ * In the case of src doesn't points utf16 string, the behavior is unspecified.
+ *
* @param src The utf16 sequence to be examined.
* @param maxlen Maximum length of src, -1 means until 0.
+ * @returns The im_utf16_strlen() function shall return the length of s.
*/
IMSize im_utf16_strlen (const IMUInt16 *src,
IMInt maxlen);
Modified: trunk/imbus/src/im_utilities.h
==============================================================================
--- trunk/imbus/src/im_utilities.h (original)
+++ trunk/imbus/src/im_utilities.h Mon Nov 19 05:59:17 2007
@@ -46,6 +46,16 @@
* without changing the ordering.
*
*
+ * The im_lower_bound() function searches for the first place that
+ * val can be inserted into the ordered range defined by ...
+ *
+ * The return value of im_lower_bound() is a pointer that points to the
+ *
+ * The comparison function shall return an integer less than, equal
to, or
+ * greater than zefo if the first argument is considered to be
respectively less than,
+ * equal to, or greater than the second. If two members compare as
equal, their order
+ * in the sorted array is undefined.
+ *
* @param base Pointer of the array.
* @param total_elems Total elements in the array.
* @param size Size of each element.
@@ -66,6 +76,11 @@
* @brief Finds the last position in which val could be inserted
* without changing the ordering.
*
+ * The comparison function shall return an integer less than, equal
to, or
+ * greater than zero if the first argument is considered to be
respectively less than,
+ * equal to, or greater than the second. If two members compare as
equal, their order
+ * in the sorted array is undefined.
+ *
* @param base Pointer of the array.
* @param total_elems Total elements in the array.
* @param size Size of each element.
@@ -86,6 +101,11 @@
* @brief Finds the first position in which val could be inserted
* without changing the ordering.
*
+ * The comparison function shall return an integer less than, equal
to, or
+ * greater than zero if the first argument is considered to be
respectively less than,
+ * equal to, or greater than the second. If two members compare as
equal, their order
+ * in the sorted array is undefined.
+ *
* @param base Pointer of the array.
* @param total_elems Total elements in the array.
* @param size Size of each element.
@@ -107,6 +127,11 @@
* @brief Finds the last position in which val could be inserted
* without changing the ordering.
*
+ * The comparison function shall return an integer less than, equal
to, or
+ * greater than zero if the first argument is considered to be
respectively less than,
+ * equal to, or greater than the second. If two members compare as
equal, their order
+ * in the sorted array is undefined.
+ *
* @param base Pointer of the array.
* @param total_elems Total elements in the array.
* @param size Size of each element.
@@ -135,6 +160,14 @@
/**
* @brief Calculate CRC32 checksum of a buffer.
+ *
+ * The im_calculate_crc32() function shall compute The CRC32 value.
+ *
+ * CRC32 value is caluculated with nbytes bytes from the data pointed
to by buf.
+ *
+ *
+ * @return The im_caluculate_crc32() function shall return CRC32 value
generated with buf.
+ * If buf is a null pointer or nbytes is 0, The im_calculate_crc32()
function returns 0.
*/
IMUInt32 im_calculate_crc32 (const IMChar *buf,
IMSize nbytes);
Modified: trunk/imbus/src/im_value.h
==============================================================================
--- trunk/imbus/src/im_value.h (original)
+++ trunk/imbus/src/im_value.h Mon Nov 19 05:59:17 2007
@@ -173,7 +173,7 @@
*
* @param *value a IMValue object.
*
- * @return void.
+ * @return The im_value_clear() function shall not return a value.
*/
void im_value_clear (IMValue *value);
@@ -183,7 +183,7 @@
* @param *value a IMValue object.
* @param v_char a char value to be stored into the IMValue object.
*
- * @return void.
+ * @return The im_value_set_char() function shall not return a value.
*/
void im_value_set_char (IMValue *value,
IMChar v_char);
@@ -201,7 +201,7 @@
* @param *value a IMValue object.
* @param v_uchar a unsigned char value to be stored into the IMValue object.
*
- * @return void.
+ * @return The im_value_set_uchar() function shall not return a value.
*/
void im_value_set_uchar (IMValue *value,
IMUChar v_uchar);
@@ -219,7 +219,7 @@
* @param *value a IMValue object.
* @param v_bool a bool value to be stored into the IMValue object.
*
- * @return void.
+ * @return The im_value_set_bool() function shall not return a value.
*/
void im_value_set_bool (IMValue *value,
IMBool v_bool);
@@ -237,7 +237,7 @@
* @param *value a IMValue object.
* @param v_int32 an int16 value to be stored into the IMValue object.
*
- * @return void.
+ * @return The im_value_set_int16() function shall not return a value.
*/
void im_value_set_int16 (IMValue *value,
IMInt16 v_int32);
@@ -255,7 +255,7 @@
* @param *value a IMValue object.
* @param v_uint32 a unsigned int16 value to be stored into the
IMValue object.
*
- * @return void.
+ * @return The im_value_set_uint16() function shall not return a value.
*/
void im_value_set_uint16 (IMValue *value,
IMUInt16 v_uint32);
@@ -273,7 +273,7 @@
* @param *value a IMValue object.
* @param v_int32 an int32 value to be stored into the IMValue object.
*
- * @return void.
+ * @return The im_value_set_int32() function shall not return a value.
*/
void im_value_set_int32 (IMValue *value,
IMInt32 v_int32);
@@ -291,7 +291,7 @@
* @param *value a IMValue object.
* @param v_uint32 a unsigned int32 value to be stored into the
IMValue object.
*
- * @return void.
+ * @return The im_value_set_uint32() function shall not return a value.
*/
void im_value_set_uint32 (IMValue *value,
IMUInt32 v_uint32);
@@ -309,7 +309,7 @@
* @param *value a IMValue object.
* @param v_int64 an int64 value to be stored into the IMValue object.
*
- * @return void.
+ * @return The im_value_set_int64() function shall not return a value.
*/
void im_value_set_int64 (IMValue *value,
IMInt64 v_int64);
@@ -327,7 +327,7 @@
* @param *value a IMValue object.
* @param v_uint64 a unsigned int64 value to be stored into the
IMValue object.
*
- * @return void.
+ * @return The im_value_set_uint64() function shall not return a value.
*/
void im_value_set_uint64 (IMValue *value,
IMUInt64 v_uint64);
@@ -345,7 +345,7 @@
* @param *value a IMValue object.
* @param v_double a double value to be stored into the IMValue object.
*
- * @return void.
+ * @return The im_value_set_double() function shall not return a value.
*/
void im_value_set_double (IMValue *value,
IMDouble v_double);
@@ -363,7 +363,7 @@
* @param *value a IMValue object.
* @param v_pointer a pointer to be stored into the IMValue object.
*
- * @return void.
+ * @return The im_value_set_pointer() function shall not return a value.
*/
void im_value_set_pointer (IMValue *value,
IMPointer v_pointer);
@@ -385,7 +385,7 @@
* @param *value a IMValue object.
* @param *v_string a string to be stored into the IMValue object.
*
- * @return void
+ * @return The im_value_set_c_string() function shall not return a value.
*/
void im_value_set_c_string (IMValue *value,
const IMChar *v_string);
@@ -402,7 +402,7 @@
* @param *value a IMValue object.
* @param *v_string a string to be stored into the IMValue object.
*
- * @return void
+ * @return The im_value_set_static_c_string() function shall not
return a value.
*/
void im_value_set_static_c_string(IMValue *value,
const IMChar *v_string);
@@ -460,7 +460,7 @@
* @param *value a IMValue object.
* @param v_object an object to stored.
*
- * @return void.
+ * @return The im_value_set_object() shall not return a value.
*/
void im_value_set_object (IMValue *value,
IMPointer v_object);
@@ -468,6 +468,11 @@
/**
* @brief Get the object holded b a IMValue object.
*
+ * The im_value_get_object() function shall return a pointer to an IMObject,
+ *
+ * A null pointer is returned if the value is a null pointer, or the
value doesn't containe
+ * a pointer to an IMObject.
+ *
* Pointer to the object will be returned. If this object will
continue to
* be used afer destroying the IMValue object, im_object_ref() should
be called
* against it to increase its reference count.
@@ -475,15 +480,26 @@
* @param *value a IMValue object.
*
* @return IMPointer a Pointer to object.
+ *
+ * @see im_value_dup_object
*/
IMPointer im_value_get_object (const IMValue *value);
/**
* @brief Duplicate the object holded by a value.
*
- * @param *value a IMValue object.
+ * The im_value_dup_object() function shall return a pointer to a IMObject,
+ * which is a duplicate of the IMObject that the value holds.
+ *
+ * The returned IMPointer can be passed to im_object_unref().
+ *
+ * A null pointer is returned if the value is a null pointer, or the
value doesn't contain
+ * a pointer to an IMObject.
+ *
+ * @param *value an IMValue object.
*
- * @return IMPointer a pointer to a cloned object. Must be released by im_object_unref();
+ * @return The im_value_dup_object() function shall return IMPointer
points to an IMObject which is hold by value.
+ *
*/
IMPointer im_value_dup_object (const IMValue *value);