[imbus commit] r34 - trunk/imbus/src
codesite...@google.com
Date: Tue Oct 23 01:53:51 2007
New Revision: 34
Modified:
trunk/imbus/src/im_component_info.h
trunk/imbus/src/im_quark.h
trunk/imbus/src/im_value.h
Log:
document update
Modified: trunk/imbus/src/im_component_info.h
==============================================================================
--- trunk/imbus/src/im_component_info.h (original)
+++ trunk/imbus/src/im_component_info.h Tue Oct 23 01:53:51 2007
@@ -17,11 +17,16 @@
* @brief IMComponentInfo class is used to hold various information of an
* IMBUS component.
*
+ * IMComponent class shall consist the following kinds of data members
of a candidate phrase.
+ *
* An IMComponentInfo object contains the following information of an IMBUS
* component:
- * - Unique ID (IMUInt32)
- * Unique ID of the component allocated by IMBUS. This field is meanless
- * before registering the component into IMBUS.
+ *
+ * - Unique ID: \n
+ * type IMUInt32
+ * An unique id of the component.
+ * The default value of unique id is IM_EVENT_SOURCE_INVALID
+ * The id is allocated and assigned by IMBUS.
* - Unique string ID (IMString)
* An unique string ID of the component. Components registered into IMBUS
* shall have unique string IDs, unless the string ID is empty.
@@ -35,6 +40,9 @@
* Icon file of the component that will be shown to user.
* - IMEventRoles
* An IMEventRoles object containing event roles supported by the component.
+ *
+ * The data members in IMComponentInfo instance shall only be set
by ... methods.
+ * The default value of those data members not even set once by
avobe methods are NIL
*/
IM_BEGIN_DECLS
Modified: trunk/imbus/src/im_quark.h
==============================================================================
--- trunk/imbus/src/im_quark.h (original)
+++ trunk/imbus/src/im_quark.h Tue Oct 23 01:53:51 2007
@@ -18,15 +18,18 @@
typedef IMUInt32 IMQuark;
/**
- * @brief Gets the IMQuark associated with the given string,
- * or 0 if the string has no associated IMQuark.
+ * @brief Gets the IMQuark associated with the given string.
*
- * If you want the IMQuark to be created if it doesn't already exist,
- * use im_quark_from_string() or im_quark_from_static_string()
+ * 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().
*
- * @param string a string.
+ * When 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.
+ *
+ * @param a pointer to an IMChar which specifies an name associated
with the quark identifier.
* @return the IMQuark associated with the string,
- * or 0 if there is no 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().
+ * @sa im_quark_from_string() im_quark_from_static_string()
*/
IMQuark im_quark_try_string (const IMChar *string);
/**
@@ -34,6 +37,8 @@
* 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.
+ *
* Note that this function is identical to im_quark_from_string()
* except that if a new IMQuark is created the string itself is used
* rather than a copy. This saves memory, but can only be used if the
@@ -42,8 +47,9 @@
* in dynamically loaded modules, if you expect to ever unload the
* module again.
*
- * @param string a string.
+ * @param a pointer to an IMChar which specifies an name associated
with the quark identifier.
* @return the IMQuark identifying the string.
+ * @sa im_quark_try_string() im_quark_from_string()
*/
IMQuark im_quark_from_static_string (const IMChar *string);
/**
@@ -52,7 +58,9 @@
* IMQuark, a new IMQuark is created, using a copy of
* the string.
*
- * @param string a string.
+ * im_quark_from_string() function shall return IMQuark associated
with the string.
+ *
+ * @param a pointer to an IMChar which specifies an name associated
with the quark identifier.
* @return the IMQuark identifying the string.
*/
IMQuark im_quark_from_string (const IMChar *string);
Modified: trunk/imbus/src/im_value.h
==============================================================================
--- trunk/imbus/src/im_value.h (original)
+++ trunk/imbus/src/im_value.h Tue Oct 23 01:53:51 2007
@@ -410,12 +410,13 @@
/**
* @brief Take an ownership holded in a newly allocated string.
*
+ * The im_value_take_c_string() function shall
* The string will be freed when destroying the IMValue object.
*
* @param *value a IMValue object.
* @param *v_string a string to be stored into the IMValue object.
*
- * @return void
+ * @return The im_value_take_c_string() function shall not return a value.
*/
void im_value_take_c_string (IMValue *value,
IMChar *v_string);
@@ -423,14 +424,14 @@
/**
* @brief Get the string held by an IMValue object.
*
- * The string pointer holded by the IMValue object will be returned, it
- * must not be freed or modified outside the IMValue object.
+ * 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
*
- * @param *value an IMValue object.
+ * @param value a pointer to an IMValue object.
*
- * @return IMChar* The string pointer held by the IMValue object.
- * If the IMValue object specified by the value parameter is
not a type of
- * string, the return value is NULL.
+ * @return The im_value_get_c_string() function shall return a pointer
to the string
+ * in type of IMChar * on success, Otherwise it shall return
a null pointer.
*/
const IMChar* im_value_get_c_string (const IMValue *value);