API documented: IBusProperty IBusText IBusTypes

6 files changed, 310 insertions, 34 deletions

diff --git a/docs/reference/ibus/ibus-docs.sgml b/docs/reference/ibus/ibus-docs.sgml
index 424bfd1..151ea6f 100644
--- a/docs/reference/ibus/ibus-docs.sgml
+++ b/docs/reference/ibus/ibus-docs.sgml
@@ -3,9 +3,9 @@
                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
   <bookinfo>
-    <title>IBus Reference Manual</title>
+    <title>iBus Reference Manual</title>
     <releaseinfo>
-      For ibus 1.1.0
+      iBus 1.1.0 reference manual.
       The latest version of this documentation can be found on-line at
       <ulink role="online-location" url="http://code.google.com/p/ibus">http://code.google.com/p/ibus</ulink>.
     </releaseinfo>
@@ -35,25 +35,25 @@
       <title>Input method engine</title>     
       <para>
       </para>
-      <xi:include href="xml/ibushotkey.xml"/>
-      <xi:include href="xml/ibuskeysyms.xml"/>
+      <xi:include href="xml/ibusbus.xml"/>
+      <xi:include href="xml/ibusconnection.xml"/>
       <xi:include href="xml/ibusengine.xml"/>
       <xi:include href="xml/ibusenginedesc.xml"/>
+      <xi:include href="xml/ibushotkey.xml"/>
+      <xi:include href="xml/ibuskeysyms.xml"/>
   </chapter>
   <chapter>
       <title>Configure</title>     
       <para>
       </para>
+      <xi:include href="xml/ibusconfig.xml"/>
       <xi:include href="xml/ibusxml.xml"/>
   </chapter>
   <chapter>
       <title>Others</title>     
       <para>
       </para>
-      <xi:include href="xml/ibusbus.xml"/>
       <xi:include href="xml/ibuscomponent.xml"/>
-      <xi:include href="xml/ibusconfig.xml"/>
-      <xi:include href="xml/ibusconnection.xml"/>
       <xi:include href="xml/ibusdebug.xml"/>
       <xi:include href="xml/ibusenumtypes.xml"/>
       <xi:include href="xml/ibuserror.xml"/>
@@ -74,3 +74,4 @@
       <xi:include href="xml/keyname-table.xml"/>
   </chapter>
 </book>
+
diff --git a/docs/reference/ibus/ibus-sections.txt b/docs/reference/ibus/ibus-sections.txt
index 4d4d520..628dda1 100644
--- a/docs/reference/ibus/ibus-sections.txt
+++ b/docs/reference/ibus/ibus-sections.txt
@@ -90,6 +90,15 @@ IBUS_PROXY_GET_CLASS
 </SECTION>
 
 <SECTION>
+<FILE>ibustypes</FILE>
+<TITLE>IBusTypes</TITLE>
+IBusModifierType
+IBusCapabilite
+IBusRectangle
+IBusFreeFunc
+</SECTION>
+
+<SECTION>
 <FILE>ibusconfig</FILE>
 <TITLE>IBusConfig</TITLE>
 IBusConfig
@@ -516,13 +525,6 @@ ibus_xml_free
 ibus_xml_output
 </SECTION>
 
-<SECTION>
-<FILE>ibustypes</FILE>
-IBusModifierType
-IBusCapabilite
-IBusRectangle
-IBusFreeFunc
-</SECTION>
 
 <SECTION>
 <FILE>ibusmessage</FILE>
diff --git a/src/ibusattribute.h b/src/ibusattribute.h
index b6c1be8..a3907c7 100644
--- a/src/ibusattribute.h
+++ b/src/ibusattribute.h
@@ -1,12 +1,3 @@
-/**
- * SECTION: ibusattribute
- * @short_description: Attributes of IBusText.
- * @stability: Stable
- * @see_also: #IBusText
- *
- * An IBusAttribute represents an attribute that associate to IBusText.
- * It decorates preedit buffer and auxiliary text with underline, foreground and background colors.
- */
 /* vim:set et sts=4: */
 /* IBus - The Input Bus
  * Copyright (C) 2008-2009 Huang Peng <shawn.p.huang@gmail.com>
@@ -26,6 +17,15 @@
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  * Boston, MA 02111-1307, USA.
  */
+/**
+ * SECTION: ibusattribute
+ * @short_description: Attributes of IBusText.
+ * @stability: Stable
+ * @see_also: #IBusText
+ *
+ * An IBusAttribute represents an attribute that associate to IBusText.
+ * It decorates preedit buffer and auxiliary text with underline, foreground and background colors.
+ */
 #ifndef __IBUS_ATTRIBUTE_H_
 #define __IBUS_ATTRIBUTE_H_
 
@@ -106,8 +106,8 @@ typedef struct _IBusAttrListClass IBusAttrListClass;
  * @start_index: The starting index, inclusive.
  * @end_index: The ending index, exclusive.
  *
- * Signify the type, value and range of the attribute.
- * The range starts from @start_index till the @end_index-1.
+ * Signify the type, value and scope of the attribute.
+ * The scope starts from @start_index till the @end_index-1.
  */
 struct _IBusAttribute {
     IBusSerializable parent;
@@ -229,9 +229,9 @@ void                 ibus_attr_list_append      (IBusAttrList   *attr_list,
  * ibus_attr_list_get:
  * @attr_list: An IBusAttrList instance.
  * @index: Index of the @attr_list.
- * @returns: The IBusAttribute from IBusAttrList at specified index.
+ * @returns: IBusAttribute at given index, NULL if no such IBusAttribute.
  *
- * Get the IBusAttribute from IBusAttrList at specified index.
+ * Returns IBusAttribute at given index.
  */
 IBusAttribute       *ibus_attr_list_get         (IBusAttrList   *attr_list,
                                                  guint           index);
diff --git a/src/ibusproperty.h b/src/ibusproperty.h
index 7cd90c9..e94e192 100644
--- a/src/ibusproperty.h
+++ b/src/ibusproperty.h
@@ -17,6 +17,20 @@
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  * Boston, MA 02111-1307, USA.
  */
+/**
+ * SECTION: ibusproperty
+ * @short_description: UI component for input method engine property.
+ * @stability: Stable
+ * @see_also: #IBusEngine
+ *
+ * An IBusProperty is an UI component like a button or a menu item 
+ * which shows the status of corresponding input method engine property.
+ * End user can operate and see the current status of IME through these components.
+ * For example, ibus-chewing users change the English/Chinese input mode by
+ * pressing ctrl-space or click on the Eng/Chi switch button.
+ * And the IBusProperty shows the change correspondingly.
+ */
+
 #ifndef __IBUS_PROPERTY_H_
 #define __IBUS_PROPERTY_H_
 
@@ -59,7 +73,17 @@ G_BEGIN_DECLS
 #define IBUS_PROP_LIST_GET_CLASS(obj)   \
     (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_PROP_LIST, IBusPropListClass))
 
-
+/**
+ * IBusPropType:
+ * @PROP_TYPE_NORMAL: Property is shown as normal text.
+ * @PROP_TYPE_TOGGLE: Property is shown as a toggle button.
+ * @PROP_TYPE_RADIO: Property is shown as a radio selection option.
+ * @PROP_TYPE_MENU: Property is shown as a menu, usually imply it has sub menu
+ * items.
+ * @PROP_TYPE_SEPARATOR: A separator for menu.
+ *
+ * Type of IBusProperty.
+ */
 typedef enum {
     PROP_TYPE_NORMAL = 0,
     PROP_TYPE_TOGGLE = 1,
@@ -68,21 +92,58 @@ typedef enum {
     PROP_TYPE_SEPARATOR = 4,
 } IBusPropType;
 
+/**
+ * IBusPropState:
+ * @PROP_STATE_UNCHECKED: Property option is unchecked.
+ * @PROP_STATE_CHECKED: Property option is checked.
+ * @PROP_STATE_INCONSISTENT: The state is inconsistent with the associated IME
+ * property.
+ *
+ * State of IBusProperty. The actual effect depends on #IBusPropType of the
+ * IBusProperty.
+ *
+ * <variablelist>
+ *     <varlistentry>
+ *         <term>PROP_TYPE_TOGGLE</term>
+ *         <listitem><para>Emphasized if PROP_STATE_CHECKED, normal otherwise.</para></listitem>
+ *     </varlistentry>
+ *     <varlistentry>
+ *         <term>PROP_TYPE_RADIO</term>
+ *         <listitem><para>Option checked if PROP_STATE_CHECKED, unchecked otherwise.</para></listitem>
+ *     </varlistentry>
+ * </variablelist>
+ * No effect on other types.
+ */
 typedef enum {
     PROP_STATE_UNCHECKED = 0,
     PROP_STATE_CHECKED = 1,
     PROP_STATE_INCONSISTENT = 2,
 } IBusPropState;
 
-
 typedef struct _IBusProperty IBusProperty;
 typedef struct _IBusPropertyClass IBusPropertyClass;
 typedef struct _IBusPropList IBusPropList;
 typedef struct _IBusPropListClass IBusPropListClass;
 
+/**
+ * IBusProperty:
+ * @key: Unique Identity for the IBusProperty.
+ * @icon: Icon file for the IBusProperty. 
+ * @label: Text shown in UI.
+ * @tooltip: Message shown if mouse hovered the  IBusProperty.
+ * @sensitive: Whether the IBusProperty is sensitive to keyboard and mouse event.
+ * @visible: Whether the IBusProperty is visible.
+ * @type: IBusPropType of IBusProperty.
+ * @state: IBusPropState of IBusProperty.
+ * @sub_props: IBusPropList that contains sub IBusProperties. These IBusProperties are usually 
+ * shown as sub menu item.
+ *
+ * UI component for input method engine property.
+ */
 struct _IBusProperty {
     IBusSerializable parent;
-
+ 
+    /*< public >*/
     gchar    *key;
     gchar    *icon;
     IBusText *label;
@@ -100,6 +161,13 @@ struct _IBusPropertyClass {
     IBusSerializableClass parent;
 };
 
+
+/**
+ * IBusPropList:
+ * @properties: GArray that holds IBusProperties.
+ *
+ * An Array of IBusProperties.
+ */
 struct _IBusPropList {
     IBusSerializable parent;
 
@@ -111,6 +179,21 @@ struct _IBusPropListClass {
 };
 
 GType            ibus_property_get_type     ();
+/**
+ * ibus_property_new:
+ * @key: Unique Identity for the IBusProperty.
+ * @icon: Icon file for the IBusProperty. 
+ * @label: Text shown in UI.
+ * @tooltip: Message shown if mouse hovered the  IBusProperty.
+ * @sensitive: Whether the IBusProperty is sensitive to keyboard and mouse event.
+ * @visible: Whether the IBusProperty is visible.
+ * @type: IBusPropType of IBusProperty.
+ * @state: IBusPropState of IBusProperty.
+ * @sub_props: IBusPropList that contains sub IBusProperties.
+ * @returns: A newly allocated IBusProperty.
+ *
+ * New a IBusProperty.
+ */
 IBusProperty    *ibus_property_new          (const gchar    *key,
                                              IBusPropType    type,
                                              IBusText       *label,
@@ -120,19 +203,79 @@ IBusProperty    *ibus_property_new          (const gchar    *key,
                                              gboolean        visible,
                                              IBusPropState   state,
                                              IBusPropList   *prop_list);
+
+/**
+ * ibus_property_set_label:
+ * @prop: An IBusProperty.
+ * @label: Text shown in UI.
+ *
+ * Set the label of IBusProperty.
+ */
 void             ibus_property_set_label    (IBusProperty   *prop,
                                              IBusText       *label);
+
+/**
+ * ibus_property_set_visible:
+ * @prop: An IBusProperty.
+ * @visible: Whether the IBusProperty is visible.
+ *
+ * Set whether the IBusProperty is visible.
+ */
 void             ibus_property_set_visible  (IBusProperty   *prop,
                                              gboolean        visible);
+
+/**
+ * ibus_property_set_sub_props:
+ * @prop: An IBusProperty.
+ * @prop_list: IBusPropList that contains sub IBusProperties.
+ * 
+ * Set the sub IBusProperties.
+ */
 void             ibus_property_set_sub_props(IBusProperty   *prop,
                                              IBusPropList   *prop_list);
 
 GType            ibus_prop_list_get_type    ();
+
+/**
+ * ibus_prop_list_new:
+ * @returns: A newly allocated IBusPropList.
+ *
+ * New a IBusPropList.
+ */
 IBusPropList    *ibus_prop_list_new         ();
+
+/**
+ * ibus_prop_list_append:
+ * @prop_list: An IBusPropList.
+ * @prop: IBusProperty to be append to @prop_list.
+ *
+ * Append an IBusProperty to an IBusPropList.
+ */
 void             ibus_prop_list_append      (IBusPropList   *prop_list,
                                              IBusProperty   *prop);
+
+/**
+ * ibus_prop_list_get:
+ * @prop_list: An IBusPropList.
+ * @index: Index of an IBusPropList.
+ * @returns: IBusProperty at given index, NULL if no such IBusProperty.
+ *
+ * Returns IBusProperty at given index.
+ */
 IBusProperty    *ibus_prop_list_get         (IBusPropList   *prop_list,
                                              guint           index);
+
+/**
+ * ibus_prop_list_update_property:
+ * @prop_list: An IBusPropList.
+ * @prop: IBusProperty to be update.
+ * @returns: TRUE if succeeded, FALSE otherwise.
+ *
+ * Update an IBusProperty in IBusPropList.
+ *
+ * <note><para>This function is not implemented yet.</para>
+ * </note>
+ */
 gboolean         ibus_prop_list_update_property
                                             (IBusPropList   *prop_list,
                                              IBusProperty   *prop);
diff --git a/src/ibustext.h b/src/ibustext.h
index 390c970..e46cd9c 100644
--- a/src/ibustext.h
+++ b/src/ibustext.h
@@ -19,9 +19,13 @@
  */
 /**
  * SECTION: ibustext
- * @short_description: Preedit buffer and candidate handling.
+ * @short_description: Text with decorating information.
+ * @see_also: #IBusAttribute
  * 
- * iBus-text handles preedit buffer and candidate string.
+ * An IBusText is the main text object in IBus.
+ * The text is decorated according to associated IBusAttribute,
+ * e.g. the foreground/background color, underline, and
+ * applied scope.
  */
 
 #ifndef __IBUS_TEXT_H_
@@ -52,6 +56,14 @@ G_BEGIN_DECLS
 typedef struct _IBusText IBusText;
 typedef struct _IBusTextClass IBusTextClass;
 
+/**
+ * IBusText:
+ * @is_static: Whether @text is static, i.e., no need and will not be freed. Only TRUE if IBusText is newed from ibus_text_new_from_static_string().
+ * @text: The string content of IBusText in UTF-8.
+ * @attrs: Associated IBusAttributes.
+ *
+ * A text object in IBus.
+ */
 struct _IBusText {
     IBusSerializable parent;
 
@@ -66,17 +78,78 @@ struct _IBusTextClass {
 };
 
 GType            ibus_text_get_type                 (void);
+
+/**
+ * ibus_text_new_from_string:
+ * @str: An text string to be set.
+ * @returns: A newly allocated IBusText.
+ * 
+ * New an IBusText whose content is copied from a text string.
+ */
 IBusText        *ibus_text_new_from_string          (const gchar    *str);
+
+/**
+ * ibus_text_new_from_string:
+ * @str: An text string to be set.
+ * @returns: A newly allocated IBusText.
+ * 
+ * New an IBusText whose content is copied from a UCS4 encoded text string.
+ */
 IBusText        *ibus_text_new_from_ucs4            (const gunichar *str);
+
+/**
+ * ibus_text_new_from_string:
+ * @str: An text string to be set.
+ * @returns: A newly allocated IBusText.
+ * 
+ * New an IBusText whose content is from a static string.
+ * Note that it is the developer's duty to ensure @str is static.
+ */
 IBusText        *ibus_text_new_from_static_string   (const gchar    *str);
+
+/**
+ * ibus_text_new_from_string:
+ * @fmt: printf format string.
+ * @returns: A newly allocated IBusText.
+ * 
+ * New an IBusText from a printf expression.
+ */
 IBusText        *ibus_text_new_from_printf          (const gchar    *fmt,
                                                      ...);
+
+/**
+ * ibus_text_new_from_unichar:
+ * @c: A single UCS4-encoded character.
+ * @returns: A newly allocated IBusText.
+ * 
+ * New an IBusText from a single UCS4-encoded character.
+ */
 IBusText        *ibus_text_new_from_unichar         (gunichar        c);
+
+/**
+ * ibus_text_append_attribute:
+ * @text: an IBusText
+ * @type: IBusAttributeType for @text.
+ * @value: Value for the type.
+ * @start_index: The starting index, inclusive.
+ * @end_index: The ending index, exclusive.
+ * 
+ * Append an IBusAttribute for IBusText. 
+ */
 void             ibus_text_append_attribute         (IBusText       *text,
                                                      guint           type,
                                                      guint           value,
                                                      guint           start_index,
                                                      gint            end_index);
+/**
+ * ibus_text_get_length:
+ * @text: An IBusText.
+ * @returns: Number of character in @text, not counted by bytes.
+ * 
+ * Return number of characters in an IBusText.
+ * This function is based on g_utf8_strlen(), so unlike strlen(),
+ * it does not count by bytes but characters instead.
+ */
 guint            ibus_text_get_length               (IBusText       *text);
 
 G_END_DECLS
diff --git a/src/ibustypes.h b/src/ibustypes.h
index a977db4..713c7c8 100644
--- a/src/ibustypes.h
+++ b/src/ibustypes.h
@@ -17,9 +17,41 @@
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  * Boston, MA 02111-1307, USA.
  */
+/**
+ * SECTION: ibustypes
+ * @short_description: Generic types for  iBus.
+ * @stability: Stable
+ *
+ * This session consists generic types for iBus, including shift/control key modifiers,
+ * and a rectangle structure.
+ */
 #ifndef __IBUS_TYPES_H_
 #define __IBUS_TYPES_H_
 
+/**
+ * IBusModifierType:
+ * @IBUS_SHIFT_MASK: Shift  is activated.
+ * @IBUS_LOCK_MASK: Cap Lock is locked.
+ * @IBUS_CONTROL_MASK: Control key is activated.
+ * @IBUS_MOD1_MASK: Modifier 1 (Usually Alt_L (0x40),  Alt_R (0x6c),  Meta_L (0xcd)) activated.
+ * @IBUS_MOD2_MASK: Modifier 2 (Usually Num_Lock (0x4d)) activated.
+ * @IBUS_MOD3_MASK: Modifier 3 activated.
+ * @IBUS_MOD4_MASK: Modifier 4 (Usually Super_L (0xce),  Hyper_L (0xcf)) activated.
+ * @IBUS_MOD5_MASK: Modifier 5 (ISO_Level3_Shift (0x5c),  Mode_switch (0xcb)) activated.
+ * @IBUS_BUTTON1_MASK: Mouse button 1 (left) is activated.
+ * @IBUS_BUTTON2_MASK: Mouse button 2 (middle) is activated.
+ * @IBUS_BUTTON3_MASK: Mouse button 3 (right) is activated.
+ * @IBUS_BUTTON4_MASK: Mouse button 4 (scroll up) is activated.
+ * @IBUS_BUTTON5_MASK: Mouse button 5 (scroll down) is activated.
+ * @IBUS_FORWARD_MASK: Forward mask. 
+ * @IBUS_SUPER_MASK: Super (Usually Win) key is activated.
+ * @IBUS_HYPER_MASK: Hyper key is activated.
+ * @IBUS_RELEASE_MASK: Key is released.
+ * @IBUS_MODIFIER_MASK: Modifier mask for the all the masks above.
+ *
+ * Handles key modifier such as control, shift and alt and release event.
+ * Note that nits 15 - 25 are currently unused, while bit 29 is used internally.
+ */
 typedef enum
 {
     IBUS_SHIFT_MASK    = 1 << 0,
@@ -40,7 +72,7 @@ typedef enum
      * Bits 15 - 25 are currently unused. Bit 29 is used internally.
      */
 
-    /* forard mask */
+    /* forward mask */
     IBUS_FORWARD_MASK  = 1 << 25,
 
     IBUS_SUPER_MASK    = 1 << 26,
@@ -52,6 +84,16 @@ typedef enum
     IBUS_MODIFIER_MASK = 0x5c001fff
 } IBusModifierType;
 
+/**
+ * IBusCapabilite:
+ * @IBUS_CAP_PREEDIT_TEXT: UI is capable to show pre-edit text.
+ * @IBUS_CAP_AUXILIARY_TEXT: UI is capable to show auxiliary text.
+ * @IBUS_CAP_LOOKUP_TABLE: UI is capable to show the lookup table.
+ * @IBUS_CAP_FOCUS: UI is capable to get focus.
+ * @IBUS_CAP_PROPERTY: UI is capable to have property.
+ *
+ * Capability flags of UI.
+ */
 typedef enum {
     IBUS_CAP_PREEDIT_TEXT       = 1 << 0,
     IBUS_CAP_AUXILIARY_TEXT     = 1 << 1,
@@ -60,6 +102,15 @@ typedef enum {
     IBUS_CAP_PROPERTY           = 1 << 4,
 } IBusCapabilite;
 
+/**
+ * IBusRectangle:
+ * @x: x coordinate. 
+ * @y: y coordinate. 
+ * @width: width of the rectangle.
+ * @height: height of the renctangl.
+ *
+ * Rectangle definition.
+ */
 typedef struct _IBusRectangle IBusRectangle;
 struct _IBusRectangle {
     gint x;
@@ -68,7 +119,13 @@ struct _IBusRectangle {
     gint height;
 };
 
-typedef void (* IBusFreeFunc) (gpointer );
+/**
+ * IBusFreeFunc:
+ * @object object to be freed.
+ * 
+ * Free function prototype.
+ */
+typedef void (* IBusFreeFunc) (gpointer object);
 
 #endif