API DOC of IBusEngine, IBusEngineDesc

10 files changed, 420 insertions, 37 deletions

diff --git a/docs/reference/ibus/ibus-docs.sgml b/docs/reference/ibus/ibus-docs.sgml
index 151ea6f..a106531 100644
--- a/docs/reference/ibus/ibus-docs.sgml
+++ b/docs/reference/ibus/ibus-docs.sgml
@@ -36,9 +36,11 @@
       <para>
       </para>
       <xi:include href="xml/ibusbus.xml"/>
+      <xi:include href="xml/ibuscomponent.xml"/>
       <xi:include href="xml/ibusconnection.xml"/>
       <xi:include href="xml/ibusengine.xml"/>
       <xi:include href="xml/ibusenginedesc.xml"/>
+      <xi:include href="xml/ibusfactory.xml"/>
       <xi:include href="xml/ibushotkey.xml"/>
       <xi:include href="xml/ibuskeysyms.xml"/>
   </chapter>
@@ -47,17 +49,16 @@
       <para>
       </para>
       <xi:include href="xml/ibusconfig.xml"/>
+      <xi:include href="xml/ibusconfigservice.xml"/>
       <xi:include href="xml/ibusxml.xml"/>
   </chapter>
   <chapter>
       <title>Others</title>     
       <para>
       </para>
-      <xi:include href="xml/ibuscomponent.xml"/>
       <xi:include href="xml/ibusdebug.xml"/>
       <xi:include href="xml/ibusenumtypes.xml"/>
       <xi:include href="xml/ibuserror.xml"/>
-      <xi:include href="xml/ibusfactory.xml"/>
       <xi:include href="xml/ibusinputcontext.xml"/>
       <xi:include href="xml/ibusinternal.xml"/>
       <xi:include href="xml/ibusmarshalers.xml"/>
diff --git a/src/ibusbus.c b/src/ibusbus.c
index 52631e8..ce4b84c 100644
--- a/src/ibusbus.c
+++ b/src/ibusbus.c
@@ -377,7 +377,16 @@ ibus_bus_set_watch_dbus_signal (IBusBus        *bus,
     }
 }
 
-
+/*
+ * ibus_bus_call:
+ * @bus: An IBusBus
+ * @name: 
+ * @path:
+ * @interface:
+ * @member:
+ * @first_arg_type:
+ * @returns: TRUE if succeed, FALSE otherwise.
+ */
 static gboolean
 ibus_bus_call (IBusBus      *bus,
                const gchar  *name,
diff --git a/src/ibusbus.h b/src/ibusbus.h
index 4a07d7c..0550a9a 100644
--- a/src/ibusbus.h
+++ b/src/ibusbus.h
@@ -86,7 +86,7 @@ IBusBus     *ibus_bus_new               (void);
 
 /**
  * ibus_bus_is_connected:
- * @bus: the IBusBus instance to be processed.
+ * @bus: An IBusBus.
  * @returns: TRUE if @bus is connected, FALSE otherwise.
  *
  * Return TRUE if @bus is connected to iBus daemon.
@@ -96,7 +96,7 @@ gboolean     ibus_bus_is_connected      (IBusBus        *bus);
 
 /**
  * ibus_bus_get_connection:
- * @bus: the IBusBus instance to be processed.
+ * @bus: An IBusBus.
  * @returns: TRUE if @bus is connected, FALSE otherwise.
  *
  * Return IBusConnection of an IBusIBus instance.
@@ -111,6 +111,7 @@ const gchar *ibus_bus_hello             (IBusBus        *bus);
  * ibus_bus_request_name:
  * @bus: the IBusBus instance to be processed.
  * @name: Name to be requested.
+ * @flags: Flags (FixMe).
  * @returns: 0 if failed; positive number otherwise.
  * 
  * Request a name from iBus daemon.
@@ -120,7 +121,7 @@ guint        ibus_bus_request_name      (IBusBus        *bus,
                                          guint           flags);
 /**
  * ibus_bus_release_name:
- * @bus: the IBusBus instance to be processed.
+ * @bus: An IBusBus.
  * @name: Name to be released.
  * @returns: 0 if failed; positive number otherwise.
  * 
@@ -128,13 +129,54 @@ guint        ibus_bus_request_name      (IBusBus        *bus,
  */
 guint        ibus_bus_release_name      (IBusBus        *bus,
                                          const gchar    *name);
+
+/**
+ * ibus_bus_name_has_owner:
+ * @bus: An IBusBus.
+ * @name: Name to be released.
+ * @returns: TRUE if the name has owner, FALSE otherwise.
+ * 
+ * Whether the name has owner.
+ */
 gboolean     ibus_bus_name_has_owner    (IBusBus        *bus,
                                          const gchar    *name);
+
+/**
+ * ibus_bus_list_names:
+ * @bus: An IBusBus.
+ * @returns: Lists that attached to @bus.
+ * 
+ * Return lists that attached to @bus.
+ * <note><para>[FixMe] Not implemented yet, only return NULL.</para></note>
+ */
 GList       *ibus_bus_list_names        (IBusBus        *bus);
+
+/**
+ * ibus_bus_add_match:
+ * @bus: An IBusBus.
+ * @rule: Match rule.
+ * 
+ * Add a match rule to an IBusBus.
+ */
 void         ibus_bus_add_match         (IBusBus        *bus,
                                          const gchar    *rule);
+/**
+ * ibus_bus_remove_match:
+ * @bus: An IBusBus.
+ * @rule: Match rule.
+ * 
+ * Remove a match rule to an IBusBus.
+ */
 void         ibus_bus_remove_match      (IBusBus        *bus,
                                          const gchar    *rule);
+/**
+ * ibus_bus_get_name_owner:
+ * @bus: An IBusBus.
+ * @name: Name.
+ * @returns: Owner of the name.
+ * 
+ * Return the name owner.
+ */
 const gchar *ibus_bus_get_name_owner    (IBusBus        *bus,
                                          const gchar    *name);
 /* declare ibus methods */
@@ -146,6 +188,7 @@ IBusInputContext
                                          const gchar    *client_name);
 gboolean     ibus_bus_register_component(IBusBus        *bus,
                                          IBusComponent  *component);
+
 GList       *ibus_bus_list_engines      (IBusBus        *bus);
 GList       *ibus_bus_list_active_engines
                                         (IBusBus        *bus);
diff --git a/src/ibusengine.c b/src/ibusengine.c
index d924e25..6664751 100644
--- a/src/ibusengine.c
+++ b/src/ibusengine.c
@@ -190,6 +190,11 @@ ibus_engine_class_init (IBusEngineClass *klass)
 
 
     /* install properties */
+    /** 
+     * IBusEngine:name:
+     *
+     * Name of this IBusEngine.
+     */
     g_object_class_install_property (gobject_class,
                     PROP_NAME,
                     g_param_spec_string ("name",
@@ -199,6 +204,11 @@ ibus_engine_class_init (IBusEngineClass *klass)
                         G_PARAM_READWRITE |  G_PARAM_CONSTRUCT_ONLY));
 
 
+    /** 
+     * IBusEngine:connection:
+     *
+     * Connection for this IBusEngine.
+     */
     g_object_class_install_property (gobject_class,
                     PROP_CONNECTION,
                     g_param_spec_object ("connection",
@@ -208,6 +218,15 @@ ibus_engine_class_init (IBusEngineClass *klass)
                         G_PARAM_READWRITE |  G_PARAM_CONSTRUCT_ONLY));
 
     /* install signals */
+    /** 
+     * IBusEngine::process-key-event:
+     * @engine: An IBusEngine.
+     * @keyval: KeySym of the key press.
+     * @state: Key modifier flags
+     *
+     * This signal is emitted whenever a key event is received.
+     * Implement process_key_event() in extend class to receive this signal.
+     */
     engine_signals[PROCESS_KEY_EVENT] =
         g_signal_new (I_("process-key-event"),
             G_TYPE_FROM_CLASS (gobject_class),
@@ -220,6 +239,13 @@ ibus_engine_class_init (IBusEngineClass *klass)
             G_TYPE_UINT,
             G_TYPE_UINT);
 
+    /** 
+     * IBusEngine::focus-in:
+     * @engine: An IBusEngine.
+     *
+     * This signal is emitted whenever the client application get the focus.
+     * Implement focus_in() in extend class to receive this signal.
+     */
     engine_signals[FOCUS_IN] =
         g_signal_new (I_("focus-in"),
             G_TYPE_FROM_CLASS (gobject_class),
@@ -230,6 +256,13 @@ ibus_engine_class_init (IBusEngineClass *klass)
             G_TYPE_NONE,
             0);
 
+    /** 
+     * IBusEngine::focus-out:
+     * @engine: An IBusEngine.
+     *
+     * This signal is emitted whenever the client application  lost the focus.
+     * Implement focus_out() in extend class to receive this signal.
+     */
     engine_signals[FOCUS_OUT] =
         g_signal_new (I_("focus-out"),
             G_TYPE_FROM_CLASS (gobject_class),
@@ -240,6 +273,13 @@ ibus_engine_class_init (IBusEngineClass *klass)
             G_TYPE_NONE,
             0);
 
+    /** 
+     * IBusEngine::reset:
+     * @engine: An IBusEngine.
+     *
+     * This signal is emitted whenever the IME is reset.
+     * Implement reset() in extend class to receive this signal.
+     */
     engine_signals[RESET] =
         g_signal_new (I_("reset"),
             G_TYPE_FROM_CLASS (gobject_class),
@@ -250,6 +290,13 @@ ibus_engine_class_init (IBusEngineClass *klass)
             G_TYPE_NONE,
             0);
 
+    /** 
+     * IBusEngine::enable:
+     * @engine: An IBusEngine.
+     *
+     * This signal is emitted whenever the IME is enabled.
+     * Implement enable() in extend class to receive this signal.
+     */
     engine_signals[ENABLE] =
         g_signal_new (I_("enable"),
             G_TYPE_FROM_CLASS (gobject_class),
@@ -260,6 +307,13 @@ ibus_engine_class_init (IBusEngineClass *klass)
             G_TYPE_NONE,
             0);
 
+    /** 
+     * IBusEngine::disable:
+     * @engine: An IBusEngine.
+     *
+     * This signal is emitted whenever the IME is disabled.
+     * Implement disable() in extend class to receive this signal.
+     */
     engine_signals[DISABLE] =
         g_signal_new (I_("disable"),
             G_TYPE_FROM_CLASS (gobject_class),
@@ -270,6 +324,13 @@ ibus_engine_class_init (IBusEngineClass *klass)
             G_TYPE_NONE,
             0);
 
+    /** 
+     * IBusEngine::set-cursor-location:
+     * @engine: An IBusEngine.
+     *
+     * This signal is emitted whenever the location of IME is set.
+     * Implement set_cursor_location() in extend class to receive this signal.
+     */
     engine_signals[SET_CURSOR_LOCATION] =
         g_signal_new (I_("set-cursor-location"),
             G_TYPE_FROM_CLASS (gobject_class),
@@ -284,6 +345,13 @@ ibus_engine_class_init (IBusEngineClass *klass)
             G_TYPE_INT,
             G_TYPE_INT);
 
+    /** 
+     * IBusEngine::set-capabilities:
+     * @engine: An IBusEngine.
+     *
+     * This signal is emitted whenever the client application capabilities is set.
+     * Implement set_cursor_location() in extend class to receive this signal.
+     */
     engine_signals[SET_CAPABILITIES] =
         g_signal_new (I_("set-capabilities"),
             G_TYPE_FROM_CLASS (gobject_class),
@@ -295,6 +363,13 @@ ibus_engine_class_init (IBusEngineClass *klass)
             1,
             G_TYPE_UINT);
 
+    /** 
+     * IBusEngine::page-up:
+     * @engine: An IBusEngine.
+     *
+     * This signal is emitted whenever the page-up key is pressed.
+     * Implement page_up() in extend class to receive this signal.
+     */
     engine_signals[PAGE_UP] =
         g_signal_new (I_("page-up"),
             G_TYPE_FROM_CLASS (gobject_class),
@@ -305,6 +380,13 @@ ibus_engine_class_init (IBusEngineClass *klass)
             G_TYPE_NONE,
             0);
 
+    /** 
+     * IBusEngine::page-down:
+     * @engine: An IBusEngine.
+     *
+     * This signal is emitted whenever the page-down key is pressed.
+     * Implement page_down() in extend class to receive this signal.
+     */
     engine_signals[PAGE_DOWN] =
         g_signal_new (I_("page-down"),
             G_TYPE_FROM_CLASS (gobject_class),
@@ -315,6 +397,13 @@ ibus_engine_class_init (IBusEngineClass *klass)
             G_TYPE_NONE,
             0);
 
+    /** 
+     * IBusEngine::cursor-up:
+     * @engine: An IBusEngine.
+     *
+     * This signal is emitted whenever the up cursor key is pressed.
+     * Implement cursor_up() in extend class to receive this signal.
+     */
     engine_signals[CURSOR_UP] =
         g_signal_new (I_("cursor-up"),
             G_TYPE_FROM_CLASS (gobject_class),
@@ -325,6 +414,13 @@ ibus_engine_class_init (IBusEngineClass *klass)
             G_TYPE_NONE,
             0);
 
+    /** 
+     * IBusEngine::cursor-down:
+     * @engine: An IBusEngine.
+     *
+     * This signal is emitted whenever the down cursor key is pressed.
+     * Implement cursor_down() in extend class to receive this signal.
+     */
     engine_signals[CURSOR_DOWN] =
         g_signal_new (I_("cursor-down"),
             G_TYPE_FROM_CLASS (gobject_class),
@@ -335,6 +431,13 @@ ibus_engine_class_init (IBusEngineClass *klass)
             G_TYPE_NONE,
             0);
 
+    /** 
+     * IBusEngine::property-activate:
+     * @engine: An IBusEngine.
+     *
+     * This signal is emitted whenever a property is activated or change changed.
+     * Implement property_activate() in extend class to receive this signal.
+     */
     engine_signals[PROPERTY_ACTIVATE] =
         g_signal_new (I_("property-activate"),
             G_TYPE_FROM_CLASS (gobject_class),
@@ -347,6 +450,13 @@ ibus_engine_class_init (IBusEngineClass *klass)
             G_TYPE_STRING,
             G_TYPE_UINT);
 
+    /** 
+     * IBusEngine::property-show:
+     * @engine: An IBusEngine.
+     *
+     * This signal is emitted whenever a property is shown.
+     * Implement property_show() in extend class to receive this signal.
+     */
     engine_signals[PROPERTY_SHOW] =
         g_signal_new (I_("property-show"),
             G_TYPE_FROM_CLASS (gobject_class),
@@ -358,6 +468,13 @@ ibus_engine_class_init (IBusEngineClass *klass)
             1,
             G_TYPE_STRING);
 
+    /** 
+     * IBusEngine::property-hide:
+     * @engine: An IBusEngine.
+     *
+     * This signal is emitted whenever a property is hidden.
+     * Implement property_hide() in extend class to receive this signal.
+     */
     engine_signals[PROPERTY_HIDE] =
         g_signal_new (I_("property-hide"),
             G_TYPE_FROM_CLASS (gobject_class),
diff --git a/src/ibusengine.h b/src/ibusengine.h
index 1a35c06..754b45a 100644
--- a/src/ibusengine.h
+++ b/src/ibusengine.h
@@ -17,6 +17,16 @@
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  * Boston, MA 02111-1307, USA.
  */
+/**
+ * SECTION: ibusengine
+ * @short_description: Input method engine abstract.
+ * @stability: Stable
+ * @see_also: #IBusComponent, #IBusEngineDesc
+ *
+ * An IBusEngine provides infrastructure for input method engine.
+ * Developers can "extend" this class for input method engine development.
+ */
+
 #ifndef __IBUS_ENGINE_H_
 #define __IBUS_ENGINE_H_
 
@@ -49,13 +59,22 @@ G_BEGIN_DECLS
 typedef struct _IBusEngine IBusEngine;
 typedef struct _IBusEngineClass IBusEngineClass;
 
+/**
+ * IBusEngine:
+ * @enabled: Whether the engine is enabled.
+ * @has_focus: Whether the engine has focus.
+ * @cursor_area: Area of cursor.
+ * @client_capabilities: IBusCapabilite (client capabilities) flags.
+ *
+ * IBusEngine properties.
+ */
 struct _IBusEngine {
     IBusService parent;
     /* instance members */
+    /*< public >*/
     gboolean enabled;
     gboolean has_focus;
 
-    /* cursor location */
     IBusRectangle cursor_area;
     guint client_capabilities;
 };
@@ -103,48 +122,162 @@ struct _IBusEngineClass {
 };
 
 GType        ibus_engine_get_type       (void);
+
+/**
+ * ibus_engine_new:
+ * @name: Name of the IBusObject.
+ * @path: Path for IBusService.
+ * @connection: An opened IBusConnection.
+ * @returns: A newly allocated IBusEngine.
+ *
+ * New an  IBusEngine.
+ */
 IBusEngine  *ibus_engine_new            (const gchar        *name,
                                          const gchar        *path,
                                          IBusConnection     *connection);
+/**
+ * ibus_engine_commit_text:
+ * @engine: An IBusEngine.
+ * @text: String commit to IBusEngine.
+ *
+ * Commit output of input method to IBus client.
+ */
 void         ibus_engine_commit_text    (IBusEngine         *engine,
                                          IBusText           *text);
+
+/**
+ * ibus_engine_update_preedit_text:
+ * @engine: An IBusEngine.
+ * @text: Update content.
+ * @cursor_pos: Current position of cursor
+ * @visible: Whether the pre-edit buffer is visible.
+ *
+ * Update the pre-edit buffer.
+ */
 void         ibus_engine_update_preedit_text
                                         (IBusEngine         *engine,
                                          IBusText           *text,
                                          guint               cursor_pos,
                                          gboolean            visible);
+
+/**
+ * ibus_engine_show_preedit_text:
+ * @engine: An IBusEngine.
+ *
+ * Show the pre-edit buffer.
+ */
 void         ibus_engine_show_preedit_text
                                         (IBusEngine         *engine);
+/**
+ * ibus_engine_hide_preedit_text:
+ * @engine: An IBusEngine.
+ *
+ * Hide the pre-edit buffer.
+ */
 void         ibus_engine_hide_preedit_text
                                         (IBusEngine         *engine);
+
+/**
+ * ibus_engine_update_auxiliary_text:
+ * @engine: An IBusEngine.
+ * @text: Update content.
+ * @visible: Whether the auxiliary text bar is visible.
+ *
+ * Update the auxiliary bar.
+ */
 void         ibus_engine_update_auxiliary_text
                                          (IBusEngine        *engine,
                                           IBusText          *text,
                                           gboolean           visible);
+/**
+ * ibus_engine_show_auxiliary_text:
+ * @engine: An IBusEngine.
+ *
+ * Show the auxiliary bar.
+ */
 void         ibus_engine_show_auxiliary_text
                                         (IBusEngine         *engine);
+/**
+ * ibus_engine_hide_auxiliary_text:
+ * @engine: An IBusEngine.
+ *
+ * Hide the auxiliary bar.
+ */
 void         ibus_engine_hide_auxiliary_text
                                         (IBusEngine         *engine);
+
+/**
+ * ibus_engine_update_lookup_table:
+ * @engine: An IBusEngine.
+ * @lookup_table: An lookup_table.
+ * @visible: Whether the lookup_table is visible.
+ *
+ * Update the lookup table.
+ */
 void         ibus_engine_update_lookup_table
                                         (IBusEngine         *engine,
                                          IBusLookupTable    *lookup_table,
                                          gboolean            visible);
+/**
+ * ibus_engine_show_lookup_table:
+ * @engine: An IBusEngine.
+ *
+ * Show the lookup table.
+ */
 void         ibus_engine_show_lookup_table
                                         (IBusEngine         *engine);
+/**
+ * ibus_engine_hide_lookup_table:
+ * @engine: An IBusEngine.
+ *
+ * Hide the lookup table.
+ */
 void         ibus_engine_hide_lookup_table
                                         (IBusEngine         *engine);
 
+
+/**
+ * ibus_engine_forward_key_event:
+ * @engine: An IBusEngine.
+ * @keyval: KeySym. 
+ * @is_press: Where the key is pressed.
+ * @state: Key modifier flags.
+ *
+ * Forward the key event.
+ */
 void         ibus_engine_forward_key_event
                                         (IBusEngine         *engine,
                                          guint               keyval,
                                          gboolean            is_press,
                                          guint               state);
 
+/**
+ * ibus_engine_register_properties:
+ * @engine: An IBusEngine.
+ * @prop_list: Property List.
+ *
+ * Register and show properties in language bar.
+ */
 void         ibus_engine_register_properties
                                         (IBusEngine         *engine,
                                          IBusPropList       *prop_list);
+/**
+ * ibus_engine_update_property:
+ * @engine: An IBusEngine.
+ * @prop: IBusProperty to be updated.
+ *
+ * Update the state displayed in language bar.
+ */
 void         ibus_engine_update_property(IBusEngine         *engine,
                                          IBusProperty       *prop);
+
+/**
+ * ibus_engine_get_name:
+ * @engine: An IBusEngine.
+ * @returns: Name of IBusEngine. 
+ *
+ * Return the name of IBusEngine.
+ */
 const gchar *ibus_engine_get_name       (IBusEngine         *engine);
 
 G_END_DECLS
diff --git a/src/ibusenginedesc.h b/src/ibusenginedesc.h
index 1ba9153..243c92a 100644
--- a/src/ibusenginedesc.h
+++ b/src/ibusenginedesc.h
@@ -17,6 +17,22 @@
  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  * Boston, MA 02111-1307, USA.
  */
+/**
+ * SECTION: ibusenginedesc
+ * @short_description:  Input method engine description data.
+ * @stability: Stable
+ * @see_also: #IBusComponent, #IBusEngine
+ *
+ * An IBusEngineDesc stores description data of IBusEngine.
+ * The description data can either be passed to ibus_engine_desc_new(),
+ * or loaded from an XML node through ibus_engine_desc_new_from_xml_node()
+ * to construct IBusEngineDesc.
+ *
+ * However, the recommended way to load engine description data is 
+ * using ibus_component_new_from_file() to load a component file,
+ * which also includes engine description data.
+ */
+
 #ifndef __ENGINE_DESC_H_
 #define __ENGINE_DESC_H_
 
@@ -47,10 +63,26 @@ typedef struct _IBusEngineDesc IBusEngineDesc;
 typedef struct _IBusEngineDescClass IBusEngineDescClass;
 typedef struct _BusComponent BusComponent;
 
+/**
+ * IBusEngineDesc:
+ * @name: Name of the engine.
+ * @longname: Long name of the input method engine.
+ * @description: Input method engine description.
+ * @language: Language (e.g. zh, jp) supported by this input method engine.
+ * @license: License of the input method engine.
+ * @author: Author of the input method engine.
+ * @icon: Icon file of this engine.
+ * @layout: Keyboard layout
+ * @rank: Preference rank among engines, the highest ranked IME will put in
+ * the front.
+ *
+ * Input method engine description data.
+ */
 struct _IBusEngineDesc {
     IBusSerializable parent;
     /* instance members */
 
+    /*< public >*/
     gchar *name;
     gchar *longname;
     gchar *description;
@@ -69,6 +101,21 @@ struct _IBusEngineDescClass {
 };
 
 GType            ibus_engine_desc_get_type      (void);
+
+/**
+ * ibus_engine_desc_new:
+ * @name: Name of the engine.
+ * @longname: Long name of the input method engine.
+ * @description: Input method engine description.
+ * @language: Language (e.g. zh, jp) supported by this input method engine.
+ * @license: License of the input method engine.
+ * @author: Author of the input method engine.
+ * @icon: Icon file of this engine.
+ * @layout: Keyboard layout
+ * @returns: A newly allocated IBusEngineDesc.
+ *
+ * New a IBusEngineDesc.
+ */
 IBusEngineDesc  *ibus_engine_desc_new           (const gchar    *name,
                                                  const gchar    *longname,
                                                  const gchar    *description,
@@ -77,8 +124,28 @@ IBusEngineDesc  *ibus_engine_desc_new           (const gchar    *name,
                                                  const gchar    *author,
                                                  const gchar    *icon,
                                                  const gchar    *layout);
+/**
+ * ibus_engine_desc_new_from_xml_node:
+ * @node: An XML node
+ * @returns: A newly allocated IBusEngineDesc that contains description from
+ * @node.
+ *
+ * New a IBusEngineDesc from an XML node.
+ * <note><para>This function is called by ibus_component_new_from_file(),
+ *  so developers normally do not need to call it directly.
+ * </para></note>
+ */
 IBusEngineDesc  *ibus_engine_desc_new_from_xml_node
                                                 (XMLNode        *node);
+/**
+ * ibus_engine_desc_output:
+ * @info: An IBusEngineDesc
+ * @output: XML-formatted Input method engine description.
+ * @indent: Number of indent (showed as 4 spaces).
+ *
+ * Output XML-formatted input method engine description.
+ * The result will be append to GString specified in @output.
+ */
 void             ibus_engine_desc_output        (IBusEngineDesc  *info,
                                                  GString        *output,
                                                  gint            indent);
diff --git a/src/ibuslookuptable.h b/src/ibuslookuptable.h
index 242f27b..5f1e0b6 100644
--- a/src/ibuslookuptable.h
+++ b/src/ibuslookuptable.h
@@ -59,9 +59,21 @@ G_BEGIN_DECLS
 typedef struct _IBusLookupTable IBusLookupTable;
 typedef struct _IBusLookupTableClass IBusLookupTableClass;
 
+
+/**
+ * IBusLookupTable:
+ * @page_size: number of candidate shown per page.
+ * @cursor_pos: position index of cursor.
+ * @cursor_visible: whether the cursor is visible.
+ * @round: TRUE for lookup table wrap around.
+ * @candidates: Candidate words/phrases/
+ * 
+ * An IBusLookuptable stores the candidate words or phrases for users to choose from.
+ */
 struct _IBusLookupTable {
     IBusSerializable parent;
 
+    /*< public >*/
     guint page_size;
     guint cursor_pos;
     gboolean cursor_visible;
@@ -93,7 +105,7 @@ IBusLookupTable     *ibus_lookup_table_new      (guint               page_size,
                                                  gboolean            round);
 /**
  * ibus_lookup_table_append_candidate:
- * @table: The IBusLookupTable.
+ * @table: An IBusLookupTable.
  * @text: candidate word/phrase to be appended (in IBusText format).
  *
  * Append a candidate word/phrase to IBusLookupTable.
@@ -103,11 +115,12 @@ void                 ibus_lookup_table_append_candidate
                                                  IBusText           *text);
 
 /**
- * ibus_lookup_table_append_candidate:
- * @table: The IBusLookupTable.
- * @text: candidate word/phrase to be appended (in IBusText format).
+ * ibus_lookup_table_get_candidate:
+ * @table: An IBusLookupTable.
+ * @index: Index in the Lookup table.
+ * @returns: IBusText at the given index; NULL if no such IBusText.
  *
- * Append a candidate word/phrase to IBusLookupTable.
+ * Return IBusText at the given index.
  */
 IBusText            *ibus_lookup_table_get_candidate
                                                 (IBusLookupTable    *table,
@@ -115,7 +128,7 @@ IBusText            *ibus_lookup_table_get_candidate
 
 /**
  * ibus_lookup_table_set_cursor_pos:
- * @table: The IBusLookupTable.
+ * @table: An IBusLookupTable.
  * @cursor_pos: The position of cursor.
  *
  * Set the cursor position of IBusLookupTable.
@@ -126,7 +139,7 @@ void                 ibus_lookup_table_set_cursor_pos
 
 /**
  * ibus_lookup_table_get_cursor_pos:
- * @table: The IBusLookupTable.
+ * @table: An IBusLookupTable.
  * @returns: The position of cursor.
  *
  * Get the cursor position of IBusLookupTable.
@@ -135,8 +148,8 @@ guint                ibus_lookup_table_get_cursor_pos
                                                 (IBusLookupTable    *table);
 
 /**
- * ibus_lookup_table_set_visible:
- * @table: The IBusLookupTable.
+ * ibus_lookup_table_set_cursor_visible:
+ * @table: An IBusLookupTable.
  * @visible: Whether to make the cursor of @table visible.
  *
  * Set whether to make the cursor of an IBusLookupTable visible or not.
@@ -147,7 +160,7 @@ void                 ibus_lookup_table_set_cursor_visible
 
 /**
  * ibus_lookup_table_is_cursor_visible:
- * @table: The IBusLookupTable.
+ * @table: An IBusLookupTable.
  * @returns: Whether the cursor of @table is visible.
  *
  * Returns whether the cursor of an IBusLookupTable is visible.
@@ -156,17 +169,17 @@ gboolean             ibus_lookup_table_is_cursor_visible
                                                 (IBusLookupTable    *table);
 
 /**
- * ibus_lookup_table_is_cursor_visible:
- * @table: The IBusLookupTable.
- * @returns: The position of cursor.
+ * ibus_lookup_table_get_cursor_in_page:
+ * @table: An IBusLookupTable.
+ * @returns: The position of cursor in current page.
  *
- * Get the cursor position of IBusLookupTable.
+ * Get the cursor position in current page of IBusLookupTable.
  */                                                
 guint                ibus_lookup_table_get_cursor_in_page
                                                 (IBusLookupTable    *table);
 /**
  * ibus_lookup_table_set_page_size:
- * @table: The IBusLookupTable.
+ * @table: An IBusLookupTable.
  * @page_size: number of candidate shown per page.
  *
  * Set the number of candidate shown per page.
@@ -177,7 +190,7 @@ void                 ibus_lookup_table_set_page_size
 
 /**
  * ibus_lookup_table_get_page_size:
- * @table: The IBusLookupTable.
+ * @table: An IBusLookupTable.
  * @returns: Page size, i.e., number of candidate shown per page.
  *
  * Get the number of candidate shown per page.
@@ -187,7 +200,7 @@ guint                ibus_lookup_table_get_page_size
 
 /**
  * ibus_lookup_table_clear:
- * @table: The IBusLookupTable.
+ * @table: An IBusLookupTable.
  *
  * Clear and remove all candidate from an IBusLookupTable.
  */                                                
@@ -195,7 +208,7 @@ void                 ibus_lookup_table_clear    (IBusLookupTable    *table);
 
 /**
  * ibus_lookup_table_page_up:
- * @table: The IBusLookupTable.
+ * @table: An IBusLookupTable.
  * @returns: TRUE if success.
  *
  * Go to previous page of an IBusLookupTable. 
@@ -208,7 +221,7 @@ gboolean             ibus_lookup_table_page_up  (IBusLookupTable    *table);
 
 /**
  * ibus_lookup_table_page_down:
- * @table: The IBusLookupTable.
+ * @table: An IBusLookupTable.
  * @returns: TRUE if success.
  *
  * Go to next page of an IBusLookupTable. 
@@ -221,7 +234,7 @@ gboolean             ibus_lookup_table_page_down(IBusLookupTable    *table);
 
 /**
  * ibus_lookup_table_cursor_up:
- * @table: The IBusLookupTable.
+ * @table: An IBusLookupTable.
  * @returns: TRUE if success.
  *
  * Go to previous candidate of an IBusLookupTable. 
@@ -233,8 +246,8 @@ gboolean             ibus_lookup_table_page_down(IBusLookupTable    *table);
 gboolean             ibus_lookup_table_cursor_up(IBusLookupTable    *table);
 
 /**
- * ibus_lookup_table_cursor_up:
- * @table: The IBusLookupTable.
+ * ibus_lookup_table_cursor_down:
+ * @table: An IBusLookupTable.
  * @returns: TRUE if success.
  *
  * Go to next candidate of an IBusLookupTable. 
diff --git a/src/ibusproperty.h b/src/ibusproperty.h
index 1f890c1..6e90cd3 100644
--- a/src/ibusproperty.h
+++ b/src/ibusproperty.h
@@ -171,6 +171,7 @@ struct _IBusPropertyClass {
 struct _IBusPropList {
     IBusSerializable parent;
 
+    /*< public >*/
     GArray *properties;
 };
 
@@ -189,7 +190,7 @@ GType            ibus_property_get_type     ();
  * @visible: Whether the IBusProperty is visible.
  * @type: IBusPropType of IBusProperty.
  * @state: IBusPropState of IBusProperty.
- * @sub_props: IBusPropList that contains sub IBusProperties.
+ * @prop_list: IBusPropList that contains sub IBusProperties.
  * @returns: A newly allocated IBusProperty.
  *
  * New a IBusProperty.
@@ -274,9 +275,6 @@ IBusProperty    *ibus_prop_list_get         (IBusPropList   *prop_list,
  * @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,
diff --git a/src/ibustext.h b/src/ibustext.h
index e46cd9c..0144d54 100644
--- a/src/ibustext.h
+++ b/src/ibustext.h
@@ -68,6 +68,7 @@ struct _IBusText {
     IBusSerializable parent;
 
     /* members */
+    /*< public >*/
     gboolean is_static;
     gchar  *text;
     IBusAttrList *attrs;
@@ -89,7 +90,7 @@ GType            ibus_text_get_type                 (void);
 IBusText        *ibus_text_new_from_string          (const gchar    *str);
 
 /**
- * ibus_text_new_from_string:
+ * ibus_text_new_from_ucs4:
  * @str: An text string to be set.
  * @returns: A newly allocated IBusText.
  * 
@@ -98,7 +99,7 @@ IBusText        *ibus_text_new_from_string          (const gchar    *str);
 IBusText        *ibus_text_new_from_ucs4            (const gunichar *str);
 
 /**
- * ibus_text_new_from_string:
+ * ibus_text_new_from_static_string:
  * @str: An text string to be set.
  * @returns: A newly allocated IBusText.
  * 
@@ -108,8 +109,9 @@ IBusText        *ibus_text_new_from_ucs4            (const gunichar *str);
 IBusText        *ibus_text_new_from_static_string   (const gchar    *str);
 
 /**
- * ibus_text_new_from_string:
+ * ibus_text_new_from_printf:
  * @fmt: printf format string.
+ * @...: arguments for @fmt.
  * @returns: A newly allocated IBusText.
  * 
  * New an IBusText from a printf expression.
diff --git a/src/ibustypes.h b/src/ibustypes.h
index 713c7c8..c2b40de 100644
--- a/src/ibustypes.h
+++ b/src/ibustypes.h
@@ -121,7 +121,7 @@ struct _IBusRectangle {
 
 /**
  * IBusFreeFunc:
- * @object object to be freed.
+ * @object: object to be freed.
  * 
  * Free function prototype.
  */