[imbus commit] r40 - trunk/imbus/src

[codesite...@google.com]

Author: motonobu
Date: Tue Nov 20 10:42:03 2007
New Revision: 40

Modified:
trunk/imbus/src/im_quark.h

Log:
document update

Modified: trunk/imbus/src/im_quark.h
==============================================================================
--- trunk/imbus/src/im_quark.h (original)
+++ trunk/imbus/src/im_quark.h Tue Nov 20 10:42:03 2007
@@ -11,6 +11,8 @@

/** @type IMQuark
* @brief IMQuark is used to associate strings to unique ids.
+ *
+ * IMQuark is an ID that identifies a string.
*/

IM_BEGIN_DECLS
@@ -23,9 +25,12 @@
* The im_quark_try_string() function shall return IMQuark associated
with the string allocated earlier
* by im_quark_try_string() or im_quark_from_static_string().
*
- * When IMQuark associated with the string has not yet allocated by
im_quark_from_string() or im_quark_from_static_string(),
+ * If IMQuark associated with the string has not yet allocated by
im_quark_from_string() or im_quark_from_static_string(),
* im_quark_try_string() function shall return 0.
*
+ * The im_quark_try_string() function shall return 0 if string is a
null pointer.
+ *
+ *
* @param a pointer to an IMChar which specifies an name associated
with the quark identifier.
* @return the IMQuark associated with the string,
* or 0 when IMQuark associated with the string have been not
allocated yet with im_quark_from_string() or im_quark_from_static_string().
@@ -37,7 +42,14 @@
* If the string does not currently have an associated IMQuark,
* a new IMQuark is created, linked to the given string.
*
- * The im_quark_from_static_string() function shall return IMQuark
associated with the string.
+ * The im_quark_from_static_string() function shall convert from the
string to IMQuark representation.
+ * If string is a null pointer, im_quark_from_static_string() shall
return 0.
+ *
+ * If im_quark_from_static_string() function returns non zero value,
all future calls with the same string shall return
+ * the same IMQuark.
+ *
+ * The string argument im_quark_from_static_string() shall be in
permanently allocated storage.
+ *
*
* Note that this function is identical to im_quark_from_string()
* except that if a new IMQuark is created the string itself is used
@@ -52,22 +64,45 @@
* @sa im_quark_try_string() im_quark_from_string()
*/
IMQuark im_quark_from_static_string (const IMChar *string);
+
+
/**
* @brief Gets the IMQuark identifying the given string.
* If the string does not currently have an associated
* IMQuark, a new IMQuark is created, using a copy of
* the string.
*
- * im_quark_from_string() function shall return IMQuark associated
with the string.
+ * The im_quark_from_string() function shall convert from the string
to IMQuark representation.
+ * If string is a null pointer, im_quark_from_string() shall return 0.
+ *
+ * If im_quark_from_string() function returns non zero value, all
future calls with the same string shall return
+ * the same IMQuark.
+ *
+ * The string argument to im_quark_from_string() does not need to be
in a parmanently allocated storage.
*
* @param a pointer to an IMChar which specifies an name associated
with the quark identifier.
- * @return the IMQuark identifying the string.
+ * @return the IMQuark associated with the string.
+ * @sa im_quark_from_string() im_quark_try_string()
*/
IMQuark im_quark_from_string (const IMChar *string);
+
/**
* @brief Gets the string associated with the given IMQuark
*
- * @param quark a IMQuark.
+ * The im_quark_to_string() function shall return an IMQuark
representation associated with the string argument.
+ *
+ * If no string exists for the given IMQuark representation,
im_quark_to_string() function shall
+ * return NULL.
+ *
+ * If im_quark_to_string() function returns non-NULL value, all future
calls with the same IMQuark shall return
+ * the same string.
+ *
+ * If im_quark_to_string() function returns non-NULL, all future calls
with the same IMQuark shall return the
+ * same string.
+ *
+ * The string pointed to by the return value shall not be modified or freed.
+ *
+ * @param quark an IMQuark representation.
* @return the string associated with the IMQuark.
*/
const IMChar* im_quark_to_string (IMQuark quark);
@@ -76,6 +111,9 @@
* Interned strings can be compared for equality by
* comparing the pointers, instead of using strcmp().
*
+ * TODO
+ * The im_intern_string() function
+ * The string pointed to by the return value shall not be modified or freed.
* @param string a string
* @return a canonical representation for the string.
*/
@@ -85,8 +123,12 @@
* Interned strings can be compared for equality by
* comparing the pointers, instead of using strcmp().
*
+ * TODO
+ * The im_intern_static_string() function
* im_intern_static_string() does not copy the string, therefore
* string must not be freed or modified.
+ *
+ * The string pointed to by the return value shall not be modified or freed.
*
* @param string a string
* @return a canonical representation for the string.