Fix doc builds

Generate:
html/IBusEngineSimple.html

Fix:
ibuscomponent.h:137: Warning: IBus: "@Varargs" parameter is deprecated,
please use "@..." instead:
 * @Varargs: the NULL-terminated arguments of the properties and values.

ibuscomponent.h:83: Warning: IBus: GTK-Doc tag "Description:" has been
deprecated:
 * description: Detailed description of component.

../../../src/ibusenumtypes.h:13: warning: Section ibusenumtypes is not
defined in the ibus-sections.txt file.

../../../src/ibusenginesimple.h:39: warning: Section ibussimpleengine is
not defined in the ibus-sections.txt file.

../../../src/ibusinternal.h:35: warning: Section ibusinternal is not
defined in the ibus-sections.txt file.

../../../src/ibusattribute.h:138: warning: Parameter description for
ibus_attribute_new::returns is not used from source code comment block.

../../../src/ibusattribute.h:161: warning: Parameter description for
ibus_attribute_get_value::attr is missing in source code comment block.

../../../src/ibuscomponent.h:145: warning: Parameter description for
ibus_component_new_varargs::... is missing in source code comment block.

../../../src/ibusconfig.h:95: warning: Parameter description for
ibus_config_new::cancellable is missing in source code comment block.

html/IBusBus.html:3540: warning: no link for:
'ibus-bus-get-property-async' ->
(<code class="function">ibus_bus_get_property_async()</code>).

html/api-index-full.html:2989: warning: no link for:
'ibus-ibuscomposetable' -> (ibuscomposetable).

html/IBusAttribute.html:500: warning: no link for: 'FIXME:CAPS'
-> (<code class="literal">FIXME</code>).

html/ibus-ibuskeys.html:286: warning: no link for: 'IBUS-KEY-Enter'
-> (<span class="type">IBUS_KEY_Enter</span>).

html/IBusPanelService.html:574: warning: no link for:
'cursor-down-lookup-table' ->
(<code class="function">cursor_down_lookup_table()</code>).

html/IBusEngine.html:1190: warning: no link for: 'cancel-hand-writing'
-> (<code class="function">cancel_hand_writing()</code>).

Review URL: https://codereview.appspot.com/247680043

35 files changed, 852 insertions, 553 deletions

diff --git a/docs/reference/ibus/Makefile.am b/docs/reference/ibus/Makefile.am
index e39ab758..1ece234c 100644
--- a/docs/reference/ibus/Makefile.am
+++ b/docs/reference/ibus/Makefile.am
@@ -1,4 +1,25 @@
-## Process this file with automake to produce Makefile.in
+# vim:set noet ts=4:
+#
+# ibus - The Input Bus
+#
+# Copyright (c) 2007-2015 Peng Huang <shawn.p.huang@gmail.com>
+# Copyright (c) 2007-2015 Red Hat, Inc.
+# Copyright (c) 2015 Takao Fujiwara <takao.fujiwara1@gmail.com>
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2.1 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the Free Software
+# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
+# USA
 
 # We require automake 1.6 at least.
 AUTOMAKE_OPTIONS = 1.6
@@ -48,6 +69,7 @@ CFILE_GLOB=$(top_srcdir)/src/*.c
 # Header files to ignore when scanning. Use base file/dir names
 # e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
 IGNORE_HFILES= \
+	ibuscomposetable.h \
 	ibusconfigprivate.h \
 	ibusinternal.h \
 	keyname-table.h \
diff --git a/docs/reference/ibus/ibus.types b/docs/reference/ibus/ibus.types
index 8055cae5..632e9990 100644
--- a/docs/reference/ibus/ibus.types
+++ b/docs/reference/ibus/ibus.types
@@ -28,3 +28,4 @@ ibus_prop_list_get_type
 ibus_input_context_get_type
 ibus_observed_path_get_type
 ibus_registry_get_type
+ibus_engine_simple_get_type
diff --git a/src/ibusattribute.h b/src/ibusattribute.h
index 7f287bac..fe4cab45 100644
--- a/src/ibusattribute.h
+++ b/src/ibusattribute.h
@@ -78,7 +78,7 @@ typedef enum {
  * @IBUS_ATTR_UNDERLINE_NONE: No underline.
  * @IBUS_ATTR_UNDERLINE_SINGLE: Single underline.
  * @IBUS_ATTR_UNDERLINE_DOUBLE: Double underline.
- * @IBUS_ATTR_UNDERLINE_LOW: Low underline ? %FIXME
+ * @IBUS_ATTR_UNDERLINE_LOW: Low underline ? FIXME
  * @IBUS_ATTR_UNDERLINE_ERROR: Error underline
  *
  * Type of IBusText attribute.
@@ -132,9 +132,10 @@ GType                ibus_attribute_get_type    ();
  * @value: Value of the attribute.
  * @start_index: Where attribute starts.
  * @end_index: Where attribute ends.
- * @returns: (transfer none): A newly allocated IBusAttribute.
  *
- * New an IBusAttribute.
+ * Creates a new IBusAttribute.
+ *
+ * Returns: (transfer none): A newly allocated IBusAttribute.
  */
 IBusAttribute       *ibus_attribute_new         (guint           type,
                                                  guint           value,
@@ -143,38 +144,46 @@ IBusAttribute       *ibus_attribute_new         (guint           type,
 
 /**
  * ibus_attribute_get_attr_type:
- * @returns: An enum of #IBusAttrType.
+ * @attr: An #IBusAttribute
+ *
+ * Gets an enum of #IBusAttrType.
  *
- * Returns an enum of #IBusAttrType.
+ * Returns: An enum of #IBusAttrType.
  */
 guint                ibus_attribute_get_attr_type
                                                 (IBusAttribute *attr);
 
 /**
  * ibus_attribute_get_value:
- * @returns: An unsigned int value relative with #IBusAttrType.
+ * @attr: An #IBusAttribute
  *
- * Returns an unsigned int value relative with #IBusAttrType.
+ * Gets an unsigned int value relative with #IBusAttrType.
  * If the type is %IBUS_ATTR_TYPE_UNDERLINE, the return value is
  * #IBusAttrUnderline. If the type is %IBUS_ATTR_TYPE_FOREGROUND,
  * the return value is the color RGB.
+ *
+ * Returns: An unsigned int value relative with #IBusAttrType.
  */
 guint                ibus_attribute_get_value   (IBusAttribute *attr);
 
 /**
  * ibus_attribute_get_start_index:
- * @returns: A start unsigned index
+ * @attr: An #IBusAttribute
+ *
+ * Gets a start unsigned index
  *
- * Returns a start unsigned index
+ * Returns: A start unsigned index
  */
 guint                ibus_attribute_get_start_index
                                                 (IBusAttribute *attr);
 
 /**
  * ibus_attribute_get_end_index:
- * @returns: A end unsigned index
+ * @attr: An #IBusAttribute
  *
- * Returns a end unsigned index
+ * Gets an end unsigned index
+ *
+ * Returns: A end unsigned index
  */
 guint                ibus_attribute_get_end_index
                                                 (IBusAttribute *attr);
@@ -184,9 +193,10 @@ guint                ibus_attribute_get_end_index
  * @underline_type: Type of underline.
  * @start_index: Where attribute starts.
  * @end_index: Where attribute ends.
- * @returns: (transfer none): A newly allocated #IBusAttribute.
  *
- * New an underline #IBusAttribute.
+ * Creates a new underline #IBusAttribute.
+ *
+ * Returns: (transfer none): A newly allocated #IBusAttribute.
  */
 IBusAttribute       *ibus_attr_underline_new    (guint           underline_type,
                                                  guint           start_index,
@@ -196,9 +206,10 @@ IBusAttribute       *ibus_attr_underline_new    (guint           underline_type,
  * @color: Color in RGB.
  * @start_index: Where attribute starts.
  * @end_index: Where attribute ends.
- * @returns: (transfer none): A newly allocated #IBusAttribute.
  *
- * New an foreground #IBusAttribute.
+ * Creates a new foreground #IBusAttribute.
+ *
+ * Returns: (transfer none): A newly allocated #IBusAttribute.
  */
 IBusAttribute       *ibus_attr_foreground_new   (guint           color,
                                                  guint           start_index,
@@ -208,9 +219,10 @@ IBusAttribute       *ibus_attr_foreground_new   (guint           color,
  * @color: Color in RGB.
  * @start_index: Where attribute starts.
  * @end_index: Where attribute ends.
- * @returns: (transfer none): A newly allocated #IBusAttribute.
  *
- * New an background #IBusAttribute.
+ * Creates a new background #IBusAttribute.
+ *
+ * Returns: (transfer none): A newly allocated #IBusAttribute.
  */
 IBusAttribute       *ibus_attr_background_new   (guint           color,
                                                  guint           start_index,
diff --git a/src/ibusattrlist.h b/src/ibusattrlist.h
index cd8788f8..41433dfd 100644
--- a/src/ibusattrlist.h
+++ b/src/ibusattrlist.h
@@ -80,17 +80,19 @@ struct _IBusAttrListClass {
 
 /**
  * ibus_attr_list_get_type:
- * @returns: GType of IBusAttrList.
  *
- * Returns GType of IBusAttrList.
+ * Returns GType of #IBusAttrList.
+ *
+ * Returns: GType of #IBusAttrList.
  */
 GType                ibus_attr_list_get_type    ();
 
 /**
  * ibus_attr_list_new:
- * @returns: A newly allocated IBusAttrList.
  *
- * New an IBusAttrList.
+ * Creates an new #IBusAttrList.
+ *
+ * Returns: A newly allocated #IBusAttrList.
  */
 IBusAttrList        *ibus_attr_list_new         ();
 
@@ -107,9 +109,11 @@ void                 ibus_attr_list_append      (IBusAttrList   *attr_list,
  * ibus_attr_list_get:
  * @attr_list: An IBusAttrList instance.
  * @index: Index of the @attr_list.
- * @returns: (transfer none): IBusAttribute at given index, NULL if no such IBusAttribute.
  *
- * Returns IBusAttribute at given index. Borrowed reference.
+ * Returns #IBusAttribute at given index. Borrowed reference.
+ *
+ * Returns: (transfer none): #IBusAttribute at given index, %NULL if no such
+ *        #IBusAttribute.
  */
 IBusAttribute       *ibus_attr_list_get         (IBusAttrList   *attr_list,
                                                  guint           index);
diff --git a/src/ibusbus.h b/src/ibusbus.h
index fc37b258..1e0f3cc9 100644
--- a/src/ibusbus.h
+++ b/src/ibusbus.h
@@ -86,18 +86,22 @@ GType        ibus_bus_get_type          (void);
 
 /**
  * ibus_bus_new:
- * @returns: A newly allocated #IBusBus instance, and the instance is not floating.
  *
- * New an #IBusBus instance.
+ * Creates a new #IBusBus instance.
+ *
+ * Returns: A newly allocated #IBusBus instance, and the instance is not
+ * floating.
  */
 IBusBus     *ibus_bus_new               (void);
 
 /**
  * ibus_bus_new_async:
- * @returns: A newly allocated #IBusBus instance, and the instance is not floating.
  *
- * New an #IBusBus instance. The instance will asynchronously connect to the IBus
- * daemon.
+ * Creates a new #IBusBus instance. The instance will asynchronously connect
+ * to the IBus daemon.
+ *
+ * Returns: A newly allocated #IBusBus instance, and the instance is not
+ * floating.
  */
 IBusBus     *ibus_bus_new_async         (void);
 
@@ -105,18 +109,20 @@ IBusBus     *ibus_bus_new_async         (void);
 /**
  * ibus_bus_is_connected:
  * @bus: An #IBusBus.
- * @returns: %TRUE if @bus is connected, %FALSE otherwise.
  *
  * Return %TRUE if @bus is connected to IBus daemon.
+ *
+ * Returns: %TRUE if @bus is connected, %FALSE otherwise.
  */
 gboolean     ibus_bus_is_connected      (IBusBus        *bus);
 
 /**
  * ibus_bus_get_connection:
  * @bus: An #IBusBus.
- * @returns: (transfer none): A #GDBusConnection of an #IBusBus instance.
  *
- * Return #GDBusConnection of an #IBusBus instance.
+ * Gets a #GDBusConnection of an #IBusBus instance.
+ *
+ * Returns: (transfer none): A #GDBusConnection of an #IBusBus instance.
  */
 GDBusConnection *
              ibus_bus_get_connection    (IBusBus        *bus);
@@ -124,10 +130,11 @@ GDBusConnection *
 /**
  * ibus_bus_hello:
  * @bus: An #IBusBus.
- * @returns: The unique name of IBus process in DBus.
  *
  * This function sends a "HELLO" message to DBus daemon,
  * which replies the unique name of current IBus process.
+ *
+ * Returns: The unique name of IBus process in DBus.
  */
 const gchar *ibus_bus_hello             (IBusBus        *bus);
 
@@ -136,9 +143,10 @@ const gchar *ibus_bus_hello             (IBusBus        *bus);
  * @bus: the IBusBus instance to be processed.
  * @name: Name to be requested.
  * @flags: IBusBusNameFlag.
- * @returns: 0 if failed; IBusBusRequestNameReply otherwise.
  *
  * Request a name from IBus daemon synchronously.
+ *
+ * Returns: 0 if failed; IBusBusRequestNameReply otherwise.
  */
 guint32      ibus_bus_request_name      (IBusBus        *bus,
                                          const gchar    *name,
@@ -172,9 +180,10 @@ void        ibus_bus_request_name_async (IBusBus        *bus,
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *   ibus_bus_request_name_async().
  * @error: Return location for error or %NULL.
- * @returns: 0 if failed; positive number otherwise.
  *
  * Finishes an operation started with ibus_bus_request_name_async().
+ *
+ * Returns: 0 if failed; positive number otherwise.
  */
 guint       ibus_bus_request_name_async_finish
                                         (IBusBus        *bus,
@@ -185,9 +194,10 @@ guint       ibus_bus_request_name_async_finish
  * ibus_bus_release_name:
  * @bus: An #IBusBus.
  * @name: Name to be released.
- * @returns: 0 if failed; positive number otherwise.
  *
  * Release a name to IBus daemon synchronously.
+ *
+ * Returns: 0 if failed; positive number otherwise.
  */
 guint        ibus_bus_release_name      (IBusBus        *bus,
                                          const gchar    *name);
@@ -219,9 +229,10 @@ void         ibus_bus_release_name_async
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *   ibus_bus_release_name_async().
  * @error: Return location for error or %NULL.
- * @returns: 0 if failed; positive number otherwise.
  *
  * Finishes an operation started with ibus_bus_release_name_async().
+ *
+ * Returns: 0 if failed; positive number otherwise.
  */
 guint        ibus_bus_release_name_async_finish
                                         (IBusBus        *bus,
@@ -232,12 +243,12 @@ guint        ibus_bus_release_name_async_finish
  * ibus_bus_list_queued_owners:
  * @bus: An IBusBus.
  * @name: Name to be queried.
- * @returns: (transfer full) (element-type utf8):
- *           The unique bus names of connections currently queued for @name.
  *
  * Lists the unique bus names of connections currently queued for a bus name.
- *
  * FIXME add an asynchronous version.
+ *
+ * Returns: (transfer full) (element-type utf8):
+ *           The unique bus names of connections currently queued for @name.
  */
 GList *      ibus_bus_list_queued_owners
                                         (IBusBus      *bus,
@@ -247,9 +258,10 @@ GList *      ibus_bus_list_queued_owners
  * ibus_bus_name_has_owner:
  * @bus: An #IBusBus.
  * @name: Name to be checked.
- * @returns: %TRUE if the name has owner, %FALSE otherwise.
  *
  * Checks whether the name has owner synchronously.
+ *
+ * Returns: %TRUE if the name has owner, %FALSE otherwise.
  */
 gboolean     ibus_bus_name_has_owner    (IBusBus        *bus,
                                          const gchar    *name);
@@ -281,9 +293,10 @@ void         ibus_bus_name_has_owner_async
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *   ibus_bus_name_has_owner_async().
  * @error: Return location for error or %NULL.
- * @returns: %TRUE if the name has owner, %FALSE otherwise.
  *
  * Finishes an operation started with ibus_bus_name_has_owner_async().
+ *
+ * Returns: %TRUE if the name has owner, %FALSE otherwise.
  */
 gboolean     ibus_bus_name_has_owner_async_finish
                                         (IBusBus        *bus,
@@ -293,11 +306,12 @@ gboolean     ibus_bus_name_has_owner_async_finish
 /**
  * ibus_bus_list_names:
  * @bus: An #IBusBus.
- * @returns: (transfer full) (element-type utf8): Lists that attached to @bus.
  *
  * Return lists that attached to @bus.
- * <note><para>[FixMe] Not implemented yet, only return NULL.</para></note>
+ * <note><para>[FixMe] Not implemented yet, only return %NULL.</para></note>
  * <note><para>[FixMe] Add async version.</para></note>
+ *
+ * Returns: (transfer full) (element-type utf8): Lists that attached to @bus.
  */
 GList       *ibus_bus_list_names        (IBusBus        *bus);
 
@@ -305,9 +319,10 @@ GList       *ibus_bus_list_names        (IBusBus        *bus);
  * ibus_bus_add_match:
  * @bus: An #IBusBus.
  * @rule: Match rule.
- * @returns: %TRUE if the rule is added. %FALSE otherwise.
  *
  * Add a match rule to an #IBusBus synchronously.
+ *
+ * Returns: %TRUE if the rule is added. %FALSE otherwise.
  */
 gboolean     ibus_bus_add_match         (IBusBus        *bus,
                                          const gchar    *rule);
@@ -338,9 +353,10 @@ void         ibus_bus_add_match_async   (IBusBus        *bus,
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *   ibus_bus_add_match_async().
  * @error: Return location for error or %NULL.
- * @returns: %TRUE if the rule is added. %FALSE otherwise.
  *
  * Finishes an operation started with ibus_bus_add_match_async().
+ *
+ * Returns: %TRUE if the rule is added. %FALSE otherwise.
  */
 gboolean     ibus_bus_add_match_async_finish
                                         (IBusBus        *bus,
@@ -351,9 +367,10 @@ gboolean     ibus_bus_add_match_async_finish
  * ibus_bus_remove_match:
  * @bus: An #IBusBus.
  * @rule: Match rule.
- * @returns: %TRUE if the rule is removed. %FALSE otherwise.
  *
  * Remove a match rule to an #IBusBus synchronously.
+ *
+ * Returns: %TRUE if the rule is removed. %FALSE otherwise.
  */
 gboolean     ibus_bus_remove_match      (IBusBus        *bus,
                                          const gchar    *rule);
@@ -385,9 +402,10 @@ void         ibus_bus_remove_match_async
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *   ibus_bus_remove_match_async().
  * @error: Return location for error or %NULL.
- * @returns: %TRUE if the rule is removed. %FALSE otherwise.
  *
  * Finishes an operation started with ibus_bus_remove_match_async().
+ *
+ * Returns: %TRUE if the rule is removed. %FALSE otherwise.
  */
 gboolean     ibus_bus_remove_match_async_finish
                                         (IBusBus        *bus,
@@ -398,9 +416,10 @@ gboolean     ibus_bus_remove_match_async_finish
  * ibus_bus_get_name_owner:
  * @bus: An #IBusBus.
  * @name: Name.
- * @returns: Owner of the name. The returned value must be freed with g_free().
  *
  * Return the name owner synchronously.
+ *
+ * Returns: Owner of the name. The returned value must be freed with g_free().
  */
 gchar       *ibus_bus_get_name_owner    (IBusBus        *bus,
                                          const gchar    *name);
@@ -432,9 +451,10 @@ void         ibus_bus_get_name_owner_async
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *   ibus_bus_get_name_owner_async().
  * @error: Return location for error or %NULL.
- * @returns: Owner of the name. The returned value must be freed with g_free().
  *
  * Finishes an operation started with ibus_bus_get_name_owner_async().
+ *
+ * Returns: Owner of the name. The returned value must be freed with g_free().
  */
 gchar       *ibus_bus_get_name_owner_async_finish
                                         (IBusBus        *bus,
@@ -446,9 +466,10 @@ gchar       *ibus_bus_get_name_owner_async_finish
  * ibus_bus_exit:
  * @bus: An #IBusBus.
  * @restart: Whether restarting the ibus.
- * @returns: %TRUE if the "Exit" call is suceeded, %FALSE otherwise.
  *
  * Exit or restart ibus-daemon synchronously.
+ *
+ * Returns: %TRUE if the "Exit" call is suceeded, %FALSE otherwise.
  */
 gboolean     ibus_bus_exit              (IBusBus        *bus,
                                          gboolean        restart);
@@ -479,9 +500,10 @@ void        ibus_bus_exit_async         (IBusBus        *bus,
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *   ibus_bus_exit_async().
  * @error: Return location for error or %NULL.
- * @returns: %TRUE if the "Exit" call is suceeded, %FALSE otherwise.
  *
  * Finishes an operation started with ibus_bus_exit_async().
+ *
+ * Returns: %TRUE if the "Exit" call is suceeded, %FALSE otherwise.
  */
 gboolean    ibus_bus_exit_async_finish  (IBusBus        *bus,
                                          GAsyncResult   *res,
@@ -491,10 +513,11 @@ gboolean    ibus_bus_exit_async_finish  (IBusBus        *bus,
  * ibus_bus_create_input_context:
  * @bus: An #IBusBus.
  * @client_name: Name of client.
- * @returns: (transfer full): An newly allocated #IBusInputContext if the
  *      "CreateInputContext" call is suceeded, %NULL otherwise.
  *
  * Create an input context for client synchronously.
+ *
+ * Returns: (transfer full): An newly allocated #IBusInputContext if the
  */
 IBusInputContext *
             ibus_bus_create_input_context
@@ -528,10 +551,11 @@ void        ibus_bus_create_input_context_async
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *   ibus_bus_create_input_context_async().
  * @error: Return location for error or %NULL.
- * @returns: (transfer full): An newly allocated #IBusInputContext if the
- *      "CreateInputContext" call is suceeded, %NULL otherwise.
  *
  * Finishes an operation started with ibus_bus_create_input_context_async().
+ *
+ * Returns: (transfer full): An newly allocated #IBusInputContext if the
+ *      "CreateInputContext" call is suceeded, %NULL otherwise.
  */
 IBusInputContext *
              ibus_bus_create_input_context_async_finish
@@ -542,11 +566,12 @@ IBusInputContext *
 /**
  * ibus_bus_current_input_context:
  * @bus: An #IBusBus.
- * @returns: The named of currently focued #IBusInputContext if the
- *            "CurrentInputContext" call suceeded, %NULL otherwise. The return
- *            value must be freed with g_free().
  *
  * Get the current focused input context synchronously.
+ *
+ * Returns: The named of currently focued #IBusInputContext if the
+ *          "CurrentInputContext" call suceeded, %NULL otherwise. The return
+ *          value must be freed with g_free().
  */
 gchar       *ibus_bus_current_input_context
                                         (IBusBus        *bus);
@@ -576,11 +601,12 @@ void         ibus_bus_current_input_context_async
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *   ibus_bus_current_input_context_async().
  * @error: Return location for error or %NULL.
- * @returns: The named of currently focued IBusInputContext if the
- *            "CurrentInputContext" call suceeded, %NULL otherwise. The return
- *            value must be freed with g_free().
  *
  * Finishes an operation started with ibus_bus_current_input_context_async().
+ *
+ * Returns: The named of currently focued IBusInputContext if the
+ *          "CurrentInputContext" call suceeded, %NULL otherwise. The return
+ *          value must be freed with g_free().
  */
 gchar       *ibus_bus_current_input_context_async_finish
                                         (IBusBus        *bus,
@@ -591,9 +617,10 @@ gchar       *ibus_bus_current_input_context_async_finish
  * ibus_bus_register_component:
  * @bus: An #IBusBus.
  * @component: A input engine component.
- * @returns: %TRUE if the "RegisterComponent" call is suceeded, %FALSE otherwise.
  *
  * Register a componet to an #IBusBus synchronously.
+ *
+ * Returns: %TRUE if the "RegisterComponent" call is suceeded, %FALSE otherwise.
  */
 gboolean     ibus_bus_register_component
                                         (IBusBus        *bus,
@@ -626,9 +653,10 @@ void         ibus_bus_register_component_async
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *   ibus_bus_register_component_async().
  * @error: Return location for error or %NULL.
- * @returns: %TRUE if the "RegisterComponent" call is suceeded, %FALSE otherwise.
  *
  * Finishes an operation started with ibus_bus_register_component_async().
+ *
+ * Returns: %TRUE if the "RegisterComponent" call is suceeded, %FALSE otherwise.
  */
 gboolean     ibus_bus_register_component_async_finish
                                         (IBusBus        *bus,
@@ -638,9 +666,11 @@ gboolean     ibus_bus_register_component_async_finish
 /**
  * ibus_bus_list_engines:
  * @bus: An #IBusBus.
- * @returns: (transfer container) (element-type IBusEngineDesc): A List of engines.
  *
  * List engines synchronously.
+ *
+ * Returns: (transfer container) (element-type IBusEngineDesc):
+ *         A List of engines.
  */
 GList       *ibus_bus_list_engines      (IBusBus        *bus);
 
@@ -669,9 +699,11 @@ void         ibus_bus_list_engines_async
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *   ibus_bus_list_engines_async().
  * @error: Return location for error or %NULL.
- * @returns: (transfer container) (element-type IBusEngineDesc): A List of engines.
  *
  * Finishes an operation started with ibus_bus_list_engines_async().
+ *
+ * Returns: (transfer container) (element-type IBusEngineDesc):
+ *         A List of engines.
  */
 GList       *ibus_bus_list_engines_async_finish
                                         (IBusBus        *bus,
@@ -682,10 +714,12 @@ GList       *ibus_bus_list_engines_async_finish
 /**
  * ibus_bus_list_active_engines:
  * @bus: An #IBusBus.
- * @returns: (transfer container) (element-type IBusEngineDesc): A List of active engines.
  *
  * List active engines synchronously.
  *
+ * Returns: (transfer container) (element-type IBusEngineDesc):
+ *        A List of active engines.
+ *
  * Deprecated: 1.5.3: Read dconf value
  * /desktop/ibus/general/preload-engines instead.
  */
@@ -722,10 +756,12 @@ void         ibus_bus_list_active_engines_async
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *   ibus_bus_list_active_engines_async().
  * @error: Return location for error or %NULL.
- * @returns: (transfer container) (element-type IBusEngineDesc): A List of active engines.
  *
  * Finishes an operation started with ibus_bus_list_active_engines_async().
  *
+ * Returns: (transfer container) (element-type IBusEngineDesc):
+ *         A List of active engines.
+ *
  * Deprecated: 1.5.3: Read dconf value
  * /desktop/ibus/general/preload-engines instead.
  */
@@ -740,11 +776,13 @@ GList       *ibus_bus_list_active_engines_async_finish
  * ibus_bus_get_engines_by_names:
  * @bus: An #IBusBus.
  * @names: (array zero-terminated=1): A %NULL-terminated array of names.
- * @returns: (array zero-terminated=1) (transfer full): A %NULL-terminated array of engines.
  *
- * Get engines by given names synchronously. If some engine names do not exist, this function
- * will simply ignore them, and return rest of engines.
+ * Get engines by given names synchronously. If some engine names do not exist,
+ * this function will simply ignore them, and return rest of engines.
  * TODO(penghuang): add asynchronous version
+ *
+ * Returns: (array zero-terminated=1) (transfer full):
+ *         A %NULL-terminated array of engines.
  */
 IBusEngineDesc **
              ibus_bus_get_engines_by_names
@@ -754,10 +792,11 @@ IBusEngineDesc **
 /**
  * ibus_bus_get_use_sys_layout:
  * @bus: An #IBusBus.
- * @returns: %TRUE if "use_sys_layout" option is enabled.
  *
  * Check if the bus's "use_sys_layout" option is enabled or not synchronously.
  *
+ * Returns: %TRUE if "use_sys_layout" option is enabled.
+ *
  * Deprecated: 1.5.3: Read dconf value
  * /desktop/ibus/general/use_system_keyboard_layout instead.
  */
@@ -794,10 +833,11 @@ void         ibus_bus_get_use_sys_layout_async
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *   ibus_bus_get_use_sys_layout_async().
  * @error: Return location for error or %NULL.
- * @returns: TRUE if "use_sys_layout" option is enabled.
  *
  * Finishes an operation started with ibus_bus_get_use_sys_layout_async().
  *
+ * Returns: TRUE if "use_sys_layout" option is enabled.
+ *
  * Deprecated: 1.5.3: Read dconf value
  * /desktop/ibus/general/use_system_keyboard_layout instead.
  */
@@ -810,9 +850,11 @@ gboolean     ibus_bus_get_use_sys_layout_async_finish
 /**
  * ibus_bus_get_use_global_engine:
  * @bus: An #IBusBus.
- * @returns: TRUE if "use_global_engine" option is enabled.
  *
- * Check if the bus's "use_global_engine" option is enabled or not synchronously.
+ * Check if the bus's "use_global_engine" option is enabled or not
+ * synchronously.
+ *
+ * Returns: TRUE if "use_global_engine" option is enabled.
  *
  * Deprecated: 1.5.3: Currently global engine is always used.
  */
@@ -848,10 +890,11 @@ void         ibus_bus_get_use_global_engine_async
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *   ibus_bus_get_use_global_engine_async().
  * @error: Return location for error or %NULL.
- * @returns: %TRUE if "use_global_engine" option is enabled.
  *
  * Finishes an operation started with ibus_bus_get_use_global_engine_async().
  *
+ * Returns: %TRUE if "use_global_engine" option is enabled.
+ *
  * Deprecated: 1.5.3: Currently global engine is always used.
  */
 IBUS_DEPRECATED
@@ -863,10 +906,11 @@ gboolean     ibus_bus_get_use_global_engine_async_finish
 /**
  * ibus_bus_is_global_engine_enabled:
  * @bus: An #IBusBus.
- * @returns: %TRUE if the current global engine is enabled.
  *
  * Check if the current global engine is enabled or not synchronously.
  *
+ * Returns: %TRUE if the current global engine is enabled.
+ *
  * Deprecated: 1.5.3: Probably this would be used for Chrome OS only.
  * Currently global engine is always used and ibus_bus_get_global_engine()
  * returns NULL until the first global engine is assigned.
@@ -909,10 +953,11 @@ void         ibus_bus_is_global_engine_enabled_async
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *   ibus_bus_is_global_engine_enabled_async().
  * @error: Return location for error or %NULL.
- * @returns: %TRUE if the current global engine is enabled.
  *
  * Finishes an operation started with ibus_bus_is_global_engine_enabled_async().
  *
+ * Returns: %TRUE if the current global engine is enabled.
+ *
  * Deprecated: 1.5.3: Probably this would be used for Chrome OS only.
  * Currently global engine is always used and ibus_bus_get_global_engine()
  * returns NULL until the first global engine is assigned.
@@ -929,10 +974,11 @@ gboolean     ibus_bus_is_global_engine_enabled_async_finish
 /**
  * ibus_bus_get_global_engine:
  * @bus: An #IBusBus.
- * @returns: (transfer none): The description of current global engine,
- * or %NULL if there is no global engine.
  *
  * Get the description of current global engine synchronously.
+ *
+ * Returns: (transfer none): The description of current global engine,
+ * or %NULL if there is no global engine.
  */
 IBusEngineDesc *
              ibus_bus_get_global_engine (IBusBus        *bus);
@@ -962,10 +1008,11 @@ void         ibus_bus_get_global_engine_async
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *   ibus_bus_get_global_engine_async_finish().
  * @error: Return location for error or %NULL.
- * @returns: (transfer none): The description of current global engine,
- * or %NULL if there is no global engine.
  *
  * Finishes an operation started with ibus_bus_get_global_engine_async_finish().
+ *
+ * Returns: (transfer none): The description of current global engine,
+ * or %NULL if there is no global engine.
  */
 IBusEngineDesc *
              ibus_bus_get_global_engine_async_finish
@@ -977,9 +1024,10 @@ IBusEngineDesc *
  * ibus_bus_set_global_engine:
  * @bus: An #IBusBus.
  * @global_engine: A new engine name.
- * @returns: %TRUE if the global engine was set successfully.
  *
  * Set current global engine synchronously.
+ *
+ * Returns: %TRUE if the global engine was set successfully.
  */
 gboolean     ibus_bus_set_global_engine (IBusBus        *bus,
                                          const gchar    *global_engine);
@@ -1011,9 +1059,10 @@ void         ibus_bus_set_global_engine_async
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *   ibus_bus_set_global_engine_async().
  * @error: Return location for error or %NULL.
- * @returns: %TRUE if no IPC errros. %FALSE otherwise.
  *
  * Finishes an operation started with ibus_bus_set_global_engine_async().
+ *
+ * Returns: %TRUE if no IPC errros. %FALSE otherwise.
  */
 gboolean     ibus_bus_set_global_engine_async_finish
                                         (IBusBus        *bus,
@@ -1048,10 +1097,11 @@ void         ibus_bus_set_watch_ibus_signal
 /**
  * ibus_bus_get_config:
  * @bus: An #IBusBus.
- * @returns: (transfer none): An #IBusConfig object which is configurable with
- * @bus.
  *
  * Get the config instance from #IBusBus.
+ *
+ * Returns: (transfer none): An #IBusConfig object which is configurable with
+ * @bus.
  */
 IBusConfig  *ibus_bus_get_config        (IBusBus        *bus);
 
@@ -1059,9 +1109,10 @@ IBusConfig  *ibus_bus_get_config        (IBusBus        *bus);
  * ibus_bus_preload_engines:
  * @bus: An #IBusBus.
  * @names: (array zero-terminated=1): A %NULL-terminated array of engine names.
- * @returns: %TRUE if components start. %FALSE otherwise.
  *
  * Start bus components by engine names synchronously.
+ *
+ * Returns: %TRUE if components start. %FALSE otherwise.
  */
 gboolean     ibus_bus_preload_engines   (IBusBus        *bus,
                                          const gchar * const *names);
@@ -1094,9 +1145,10 @@ void         ibus_bus_preload_engines_async
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *   ibus_bus_preload_engines_async().
  * @error: Return location for error or %NULL.
- * @returns: %TRUE if component starts. %FALSE otherwise.
  *
  * Finishes an operation started with ibus_bus_preload_engines_async().
+ *
+ * Returns: %TRUE if component starts. %FALSE otherwise.
  */
 gboolean     ibus_bus_preload_engines_async_finish
                                         (IBusBus        *bus,
@@ -1107,10 +1159,11 @@ gboolean     ibus_bus_preload_engines_async_finish
  * ibus_bus_get_ibus_property:
  * @bus: An #IBusBus.
  * @property_name: property name in org.freedesktop.DBus.Properties.Get
- * @returns: (transfer full): The value in org.freedesktop.DBus.Properties.Get
- *           The returned value must be freed with g_variant_unref().
  *
  * Get org.freedesktop.DBus.Properties.
+ *
+ * Returns: (transfer full): The value in org.freedesktop.DBus.Properties.Get
+ *           The returned value must be freed with g_variant_unref().
  */
 GVariant *   ibus_bus_get_ibus_property (IBusBus        *bus,
                                          const gchar    *property_name);
@@ -1140,12 +1193,13 @@ void         ibus_bus_get_ibus_property_async
  * ibus_bus_get_ibus_property_async_finish:
  * @bus: An #IBusBus.
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
- *   ibus_bus_get_property_async().
+ *   ibus_bus_get_ibus_property_async().
  * @error: Return location for error or %NULL.
- * @returns: (transfer full): The value in org.freedesktop.DBus.Properties.Get
- *           The returned value must be freed with g_variant_unref().
  *
  * Finishes an operation started with ibus_bus_get_ibus_property_async().
+ *
+ * Returns: (transfer full): The value in org.freedesktop.DBus.Properties.Get
+ *           The returned value must be freed with g_variant_unref().
  */
 GVariant *   ibus_bus_get_ibus_property_async_finish
                                         (IBusBus        *bus,
@@ -1191,11 +1245,12 @@ void         ibus_bus_set_ibus_property_async
  * ibus_bus_set_ibus_property_async_finish:
  * @bus: An #IBusBus.
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
- *   ibus_bus_set_property_async().
+ *   ibus_bus_set_ibus_property_async().
  * @error: Return location for error or %NULL.
- * @returns: %TRUE if property is set with async. %FALSE failed.
  *
  * Finishes an operation started with ibus_bus_set_ibus_property_async().
+ *
+ * Returns: %TRUE if property is set with async. %FALSE failed.
  */
 gboolean     ibus_bus_set_ibus_property_async_finish
                                         (IBusBus        *bus,
diff --git a/src/ibuscomponent.h b/src/ibuscomponent.h
index ef83407c..3e51caa3 100644
--- a/src/ibuscomponent.h
+++ b/src/ibuscomponent.h
@@ -79,14 +79,6 @@ typedef struct _IBusComponentPrivate IBusComponentPrivate;
  *
  * An IBusComponent stores component information.
  * You can get extended values with g_object_get_properties.
- * name: Name of the component.
- * description: Detailed description of component.
- * version: Component version.
- * license: Distribution license of this component.
- * author: Author(s) of the component.
- * homepage: Homepage of the component.
- * command_line: path to component executable.
- * textdomain: Domain name for dgettext()
  */
 struct _IBusComponent {
     /*< private >*/
@@ -96,6 +88,7 @@ struct _IBusComponent {
 
     /*< public >*/
 
+    /*< private >*/
     /* padding */
     gpointer pdummy[7];  // We can add 7 pointers without breaking the ABI.
 };
@@ -118,9 +111,10 @@ GType            ibus_component_get_type        (void);
  * @homepage: Homepage of the component.
  * @command_line: path to component executable.
  * @textdomain: Domain name for dgettext()
- * @returns: A newly allocated IBusComponent.
  *
- * New an IBusComponent.
+ * Creates a new #IBusComponent.
+ *
+ * Returns: A newly allocated #IBusComponent.
  */
 IBusComponent   *ibus_component_new             (const gchar    *name,
                                                  const gchar    *description,
@@ -134,14 +128,16 @@ IBusComponent   *ibus_component_new             (const gchar    *name,
 /**
  * ibus_component_new_varargs:
  * @first_property_name: Name of the first property.
- * @Varargs: the NULL-terminated arguments of the properties and values.
+ * @...: the NULL-terminated arguments of the properties and values.
  *
- * New an IBusComponent.
+ * Creates a new #IBusComponent.
  * ibus_component_new_varargs() supports the va_list format.
  * name property is required. e.g.
  * IBusComponent *component = ibus_component_new_varargs ("name", "ibus-foo",
  *                                                        "command_line", "/usr/libexec/ibus-engine-foo --ibus",
  *                                                     NULL)
+ *
+ * Returns: A newly allocated #IBusComponent.
  */
 IBusComponent   *ibus_component_new_varargs     (const gchar    *first_property_name,
                                                  ...);
@@ -149,9 +145,10 @@ IBusComponent   *ibus_component_new_varargs     (const gchar    *first_property_
 /**
  * ibus_component_new_from_xml_node:
  * @node: Root node of component XML tree.
- * @returns: A newly allocated IBusComponent.
  *
- * New an IBusComponent from an XML tree.
+ * Creates a new #IBusComponent from an XML tree.
+ *
+ * Returns: A newly allocated #IBusComponent.
  */
 IBusComponent   *ibus_component_new_from_xml_node
                                                 (XMLNode        *node);
@@ -159,94 +156,103 @@ IBusComponent   *ibus_component_new_from_xml_node
 /**
  * ibus_component_new_from_file:
  * @filename: An XML file that contains component information.
- * @returns: A newly allocated IBusComponent.
  *
- * New an IBusComponent from an XML file.
+ * Creates a new #IBusComponent from an XML file.
  * Note that a component file usually contains engine descriptions,
  * if it does, ibus_engine_desc_new_from_xml_node() will be called
  * to load the engine descriptions.
+ *
+ * Returns: A newly allocated #IBusComponent.
  */
 IBusComponent   *ibus_component_new_from_file   (const gchar    *filename);
 
 /**
  * ibus_component_get_name:
- * @component: An IBusComponent
- * @returns: name property in IBusComponent
+ * @component: An #IBusComponent
  *
- * Return the name property in IBusComponent. It should not be freed.
+ * Gets the name property in #IBusComponent. It should not be freed.
+ *
+ * Returns: name property in #IBusComponent
  */
 const gchar     *ibus_component_get_name        (IBusComponent  *component);
 
 /**
  * ibus_component_get_description:
- * @component: An IBusComponent
- * @returns: description property in IBusComponent
+ * @component: An #IBusComponent
+ *
+ * Gets the description property in #IBusComponent. It should not be freed.
  *
- * Return the description property in IBusComponent. It should not be freed.
+ * Returns: description property in #IBusComponent
  */
 const gchar     *ibus_component_get_description (IBusComponent  *component);
 
 /**
  * ibus_component_get_version:
- * @component: An IBusComponent
- * @returns: version property in IBusComponent
+ * @component: An #IBusComponent
  *
- * Return the version property in IBusComponent. It should not be freed.
+ * Gets the version property in #IBusComponent. It should not be freed.
+ *
+ * Returns: version property in #IBusComponent
  */
 const gchar     *ibus_component_get_version     (IBusComponent  *component);
 
 /**
  * ibus_component_get_license:
- * @component: An IBusComponent
- * @returns: license property in IBusComponent
+ * @component: An #IBusComponent
+ *
+ * Gets the license property in #IBusComponent. It should not be freed.
  *
- * Return the license property in IBusComponent. It should not be freed.
+ * Returns: license property in #IBusComponent
  */
 const gchar     *ibus_component_get_license     (IBusComponent  *component);
 
 /**
  * ibus_component_get_author:
- * @component: An IBusComponent
- * @returns: author property in IBusComponent
+ * @component: An #IBusComponent
  *
- * Return the author property in IBusComponent. It should not be freed.
+ * Gets the author property in #IBusComponent. It should not be freed.
+ *
+ * Returns: author property in #IBusComponent
  */
 const gchar     *ibus_component_get_author      (IBusComponent  *component);
 
 /**
  * ibus_component_get_homepage:
- * @component: An IBusComponent
- * @returns: homepage property in IBusComponent
+ * @component: An #IBusComponent
+ *
+ * Gets the homepage property in #IBusComponent. It should not be freed.
  *
- * Return the homepage property in IBusComponent. It should not be freed.
+ * Returns: homepage property in #IBusComponent
  */
 const gchar     *ibus_component_get_homepage    (IBusComponent  *component);
 
 /**
  * ibus_component_get_exec:
- * @component: An IBusComponent
- * @returns: exec property in IBusComponent
+ * @component: An #IBusComponent
+ *
+ * Gets the exec property in #IBusComponent. It should not be freed.
  *
- * Return the exec property in IBusComponent. It should not be freed.
+ * Returns: exec property in #IBusComponent
  */
 const gchar     *ibus_component_get_exec        (IBusComponent  *component);
 
 /**
  * ibus_component_get_textdomain:
- * @component: An IBusComponent
- * @returns: textdomain property in IBusComponent
+ * @component: An #IBusComponent
  *
- * Return the textdomain property in IBusComponent. It should not be freed.
+ * Gets the textdomain property in #IBusComponent. It should not be freed.
+ *
+ * Returns: textdomain property in #IBusComponent
  */
 const gchar     *ibus_component_get_textdomain  (IBusComponent  *component);
 
 /**
  * ibus_component_add_observed_path:
- * @component: An IBusComponent
+ * @component: An #IBusComponent
  * @path: Observed path to be added.
- * @access_fs: TRUE for filling the file status; FALSE otherwise.
+ * @access_fs: %TRUE for filling the file status; %FALSE otherwise.
  *
- * Add an observed path to IBusComponent.
+ * Add an observed path to #IBusComponent.
  */
 void             ibus_component_add_observed_path
                                                 (IBusComponent  *component,
@@ -255,30 +261,32 @@ void             ibus_component_add_observed_path
 
 /**
  * ibus_component_add_engine:
- * @component: An IBusComponent
+ * @component: An #IBusComponent
  * @engine: A description of an engine.
  *
- * Add an engine to IBusComponent according to the description in @engine.
+ * Add an engine to #IBusComponent according to the description in @engine.
  */
 void             ibus_component_add_engine      (IBusComponent  *component,
                                                  IBusEngineDesc *engine);
 
 /**
  * ibus_component_get_engines:
- * @component: An IBusComponent.
- * @returns: (transfer container) (element-type IBusEngineDesc): A newly allocated GList that contains engines.
+ * @component: An #IBusComponent.
+ *
+ * Gets the engines of this component.
  *
- * Get the engines of this component.
+ * Returns: (transfer container) (element-type IBusEngineDesc):
+ * A newly allocated GList that contains engines.
  */
 GList           *ibus_component_get_engines     (IBusComponent  *component);
 
 /**
  * ibus_component_output:
- * @component: An IBusComponent.
+ * @component: An #IBusComponent.
  * @output: GString that holds the result.
  * @indent: level of indent.
  *
- * Output IBusComponent as an XML-formatted string.
+ * Output #IBusComponent as an XML-formatted string.
  * The output string can be then shown on the screen or written to file.
  */
 void             ibus_component_output          (IBusComponent  *component,
@@ -287,7 +295,7 @@ void             ibus_component_output          (IBusComponent  *component,
 
 /**
  * ibus_component_output_engines:
- * @component: An IBusComponent.
+ * @component: An #IBusComponent.
  * @output: GString that holds the result.
  * @indent: level of indent.
  *
@@ -300,21 +308,24 @@ void             ibus_component_output_engines  (IBusComponent  *component,
 
 /**
  * ibus_component_check_modification:
- * @component: An IBusComponent.
- * @returns: TRUE if at least one of the observed paths is modified; FALSE otherwise.
+ * @component: An #IBusComponent.
  *
  * Check whether the observed paths of component is modified.
+ *
+ * Returns: %TRUE if at least one of the observed paths is modified;
+ * %FALSE otherwise.
  */
 gboolean         ibus_component_check_modification
                                                 (IBusComponent  *component);
 
 /**
  * ibus_component_get_observed_paths:
- * @component: An IBusComponent.
- * @returns: (transfer container) (element-type IBusObservedPath): A
- * newly allocated GList that contains observed paths.
+ * @component: An #IBusComponent.
  *
- * Get the observed paths of this component.
+ * Gets the observed paths of this component.
+ *
+ * Returns: (transfer container) (element-type IBusObservedPath): A
+ * newly allocated GList that contains observed paths.
  */
 GList           *ibus_component_get_observed_paths
                                                 (IBusComponent *component);
diff --git a/src/ibusconfig.h b/src/ibusconfig.h
index 4bde4bd9..d7e85306 100644
--- a/src/ibusconfig.h
+++ b/src/ibusconfig.h
@@ -89,9 +89,12 @@ GType            ibus_config_get_type       (void);
 /**
  * ibus_config_new:
  * @connection: A #GDBusConnection.
- * @returns: An newly allocated #IBusConfig corresponding to @connection.
+ * @cancellable: A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
  *
- * New an #IBusConfig from existing #GDBusConnection.
+ * Create a new #IBusConfig from existing #GDBusConnection.
+ *
+ * Returns: A newly allocated #IBusConfig corresponding to @connection.
  */
 IBusConfig      *ibus_config_new            (GDBusConnection    *connection,
                                              GCancellable       *cancellable,
@@ -117,9 +120,10 @@ void             ibus_config_new_async      (GDBusConnection    *connection,
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback pass to
  *      ibus_config_new_async().
  * @error: Return location for error or %NULL.
- * @returns: A newly allocated #IBusConfig.
  *
  * Finishes an operation started with ibus_config_new_async().
+ *
+ * Returns: A newly allocated #IBusConfig.
  */
 IBusConfig      *ibus_config_new_async_finish
                                             (GAsyncResult       *res,
@@ -130,7 +134,6 @@ IBusConfig      *ibus_config_new_async_finish
  * @config: An #IBusConfig
  * @section: Section name of the configuration option.
  * @name: Name of the configure option.
- * @returns: A #GVariant or %NULL. Free with g_variant_unref().
  *
  * Get the value of a configuration option synchronously.
  *
@@ -142,6 +145,8 @@ IBusConfig      *ibus_config_new_async_finish
  * ibus-chewing, for example, stores its setting in /desktop/ibus/engine/Chewing,
  * so the section name for it is "engine/Chewing".
  * See also: ibus_config_set_value().
+ *
+ * Returns: A #GVariant or %NULL. Free with g_variant_unref().
  */
 GVariant        *ibus_config_get_value      (IBusConfig         *config,
                                              const gchar        *section,
@@ -174,10 +179,11 @@ void             ibus_config_get_value_async (IBusConfig         *config,
  * @config: A #IBusConfig.
  * @result: A #GAsyncResult.
  * @error: Return location for error or %NULL.
- * @returns: A #GVariant or %NULL if error is set. Free with g_variant_unref().
  * 
  * Finish get value of a configuration option.
  *
+ * Returns: A #GVariant or %NULL if error is set. Free with g_variant_unref().
+ *
  * See also: ibus_config_get_value_async().
  */
 GVariant        *ibus_config_get_value_async_finish
@@ -189,10 +195,11 @@ GVariant        *ibus_config_get_value_async_finish
  * ibus_config_get_values:
  * @config: An #IBusConfig
  * @section: Section name of the configuration option.
- * @returns: A #GVariant or %NULL. Free with g_variant_unref().
  *
  * Get all values in a section synchronously.
  *
+ * Returns: A #GVariant or %NULL. Free with g_variant_unref().
+ *
  * See also: ibus_config_set_value().
  */
 GVariant        *ibus_config_get_values     (IBusConfig         *config,
@@ -223,10 +230,11 @@ void             ibus_config_get_values_async(IBusConfig         *config,
  * @config: A #IBusConfig.
  * @result: A #GAsyncResult.
  * @error: Return location for error or %NULL.
- * @returns: A #GVariant or %NULL if error is set. Free with g_variant_unref().
  * 
  * Finish get values in a section.
  *
+ * Returns: A #GVariant or %NULL if error is set. Free with g_variant_unref().
+ *
  * See also: ibus_config_get_values_async().
  */
 GVariant        *ibus_config_get_values_async_finish
@@ -241,9 +249,11 @@ GVariant        *ibus_config_get_values_async_finish
  * @name: Name of the configure option its self.
  * @value: A #GVariant that holds the value. If the value is floating, the
  * function takes ownership of it.
- * @returns: %TRUE if succeed; %FALSE otherwise.
  *
  * Set the value of a configuration option synchronously.
+ *
+ * Returns: %TRUE if succeed; %FALSE otherwise.
+ *
  * See also: ibus_config_get_value().
  */
 gboolean         ibus_config_set_value      (IBusConfig         *config,
@@ -281,10 +291,11 @@ void             ibus_config_set_value_async (IBusConfig         *config,
  * @config: A #IBusConfig.
  * @result: A #GAsyncResult.
  * @error: Return location for error or %NULL.
- * @returns: %TRUE or %FALSE if error is set.
  * 
  * Finish set value of a configuration option.
  *
+ * Returns: %TRUE or %FALSE if error is set.
+ *
  * See also: ibus_config_set_value_async().
  */
 gboolean         ibus_config_set_value_async_finish
@@ -297,9 +308,11 @@ gboolean         ibus_config_set_value_async_finish
  * @config: An #IBusConfig
  * @section: Section name of the configuration option.
  * @name: Name of the configure option its self.
- * @returns: %TRUE if succeed; %FALSE otherwise.
  *
  * Remove an entry of a configuration option.
+ *
+ * Returns: %TRUE if succeed; %FALSE otherwise.
+ *
  * See also: ibus_config_get_value().
  */
 gboolean         ibus_config_unset      (IBusConfig         *config,
@@ -313,7 +326,6 @@ gboolean         ibus_config_unset      (IBusConfig         *config,
  * @config: An #IBusConfig
  * @section: (allow-none): Section name of the configuration option.
  * @name: (allow-none): Name of the configure option its self.
- * @returns: %TRUE if succeed; %FALSE otherwise.
  *
  * Subscribe to the configuration option change notification.
  *
@@ -322,6 +334,8 @@ gboolean         ibus_config_unset      (IBusConfig         *config,
  * call ibus_config_watch() with the sections they are interested in,
  * to reduce the number of D-Bus messages.
  *
+ * Returns: %TRUE if succeed; %FALSE otherwise.
+ *
  * See also: ibus_config_unwatch().
  */
 gboolean         ibus_config_watch      (IBusConfig         *config,
@@ -335,10 +349,11 @@ gboolean         ibus_config_watch      (IBusConfig         *config,
  * @config: An #IBusConfig
  * @section: (allow-none): Section name of the configuration option.
  * @name: (allow-none): Name of the configure option its self.
- * @returns: %TRUE if succeed; %FALSE otherwise.
  *
  * Unsubscribe from the configuration option change notification.
  *
+ * Returns: %TRUE if succeed; %FALSE otherwise.
+ *
  * See also: ibus_config_watch.
  */
 gboolean         ibus_config_unwatch    (IBusConfig         *config,
diff --git a/src/ibusconfigservice.h b/src/ibusconfigservice.h
index 343af97a..3f74f084 100644
--- a/src/ibusconfigservice.h
+++ b/src/ibusconfigservice.h
@@ -186,11 +186,12 @@ struct _IBusConfigServiceClass {
                                  GError              **error);
     /**
      * get_value:
-     * @config: An IBusConfig.
+     * @config: An #IBusConfig.
      * @section: section name
      * @name: value name
-     * @returns: (transfer full): The value in config associated with section and name.
      *
+     * Returns: (transfer full): The value in config associated with section
+     *         and name.
      */
     GVariant *  (* get_value)   (IBusConfigService    *config,
                                  const gchar          *section,
@@ -213,10 +214,11 @@ GType                ibus_config_service_get_type   (void);
 
 /**
  * ibus_config_service_new:
- * @connection: An GDBusConnection.
- * @returns: A newly allocated IBusConfigServices.
+ * @connection: An #GDBusConnection.
  *
- * New an IBusConfigService from an GDBusConnection.
+ * Creates an new #IBusConfigService from an #GDBusConnection.
+ *
+ * Returns: A newly allocated #IBusConfigServices.
  */
 IBusConfigService   *ibus_config_service_new        (GDBusConnection     *connection);
 
diff --git a/src/ibusdebug.h b/src/ibusdebug.h
index fdd40fcb..3ce72bd6 100644
--- a/src/ibusdebug.h
+++ b/src/ibusdebug.h
@@ -38,7 +38,7 @@
 /**
  * ibus_warning:
  * @msg: A printf formatted message to be print.
- * @args...: Necessary arguments for @msg.
+ * @...: Necessary arguments for @msg.
  *
  * A convenient wrapper for g_warning.
  * The output format will be
diff --git a/src/ibusengine.c b/src/ibusengine.c
index 4758f82f..b2a8022a 100644
--- a/src/ibusengine.c
+++ b/src/ibusengine.c
@@ -331,12 +331,13 @@ ibus_engine_class_init (IBusEngineClass *class)
      * @state: Key modifier flags.
      *
      * Emitted when a key event is received.
-     * Implement the member function process_key_event() in extended class to receive this signal.
+     * Implement the member function IBusEngineClass::process_key_event
+     * in extended class to receive this signal.
      * Both the key symbol and keycode are passed to the member function.
      * See ibus_input_context_process_key_event() for further explanation of
      * key symbol, keycode and which to use.
      *
-     * Returns: TRUE for successfully process the key; FALSE otherwise.
+     * Returns: %TRUE for successfully process the key; %FALSE otherwise.
      * See also:  ibus_input_context_process_key_event().
      *
      * <note><para>Argument @user_data is ignored in this function.</para></note>
@@ -359,7 +360,8 @@ ibus_engine_class_init (IBusEngineClass *class)
      * @engine: An IBusEngine.
      *
      * Emitted when the client application get the focus.
-     * Implement the member function focus_in() in extended class to receive this signal.
+     * Implement the member function IBusEngineClass::focus_in
+     * in extended class to receive this signal.
      *
      * See also: ibus_input_context_focus_in()
      * <note><para>Argument @user_data is ignored in this function.</para></note>
@@ -379,7 +381,8 @@ ibus_engine_class_init (IBusEngineClass *class)
      * @engine: An IBusEngine.
      *
      * Emitted when the client application  lost the focus.
-     * Implement the member function focus_out() in extended class to receive this signal.
+     * Implement the member function IBusEngineClass::focus_out
+     * in extended class to receive this signal.
      *
      * See also: ibus_input_context_focus_out()
      * <note><para>Argument @user_data is ignored in this function.</para></note>
@@ -399,7 +402,8 @@ ibus_engine_class_init (IBusEngineClass *class)
      * @engine: An IBusEngine.
      *
      * Emitted when the IME is reset.
-     * Implement the member function reset() in extended class to receive this signal.
+     * Implement the member function IBusEngineClass::reset
+     * in extended class to receive this signal.
      *
      * See also:  ibus_input_context_reset().
      * <note><para>Argument @user_data is ignored in this function.</para></note>
@@ -419,9 +423,10 @@ ibus_engine_class_init (IBusEngineClass *class)
      * @engine: An IBusEngine.
      *
      * Emitted when the IME is enabled.
-     * Implement the member function set_enable() in extended class to receive this signal.
+     * Implement the member function IBusEngineClass::enable
+     * in extended class to receive this signal.
      *
-     * See also:  ibus_input_context_enable().
+     * See also:  ibus_bus_set_global_engine().
      * <note><para>Argument @user_data is ignored in this function.</para></note>
      */
     engine_signals[ENABLE] =
@@ -439,9 +444,10 @@ ibus_engine_class_init (IBusEngineClass *class)
      * @engine: An IBusEngine.
      *
      * Emitted when the IME is disabled.
-     * Implement the member function set_disable() in extended class to receive this signal.
+     * Implement the member function IBusEngineClass::disable
+     * in extended class to receive this signal.
      *
-     * See also:  ibus_input_context_disable().
+     * See also:  ibus_bus_set_global_engine().
      * <note><para>Argument @user_data is ignored in this function.</para></note>
      */
     engine_signals[DISABLE] =
@@ -463,7 +469,8 @@ ibus_engine_class_init (IBusEngineClass *class)
      * @h: Height of the cursor.
      *
      * Emitted when the location of IME is set.
-     * Implement the member function set_cursor_location() in extended class to receive this signal.
+     * Implement the member function IBusEngineClass::set_cursor_location
+     * in extended class to receive this signal.
      *
      * See also:  ibus_input_context_set_cursor_location().
      * <note><para>Argument @user_data is ignored in this function.</para></note>
@@ -488,7 +495,8 @@ ibus_engine_class_init (IBusEngineClass *class)
      * @caps: Capabilities flags of IBusEngine, see #IBusCapabilite
      *
      * Emitted when the client application capabilities is set.
-     * Implement the member function set_capabilities() in extended class to receive this signal.
+     * Implement the member function IBusEngineClass::set_capabilities
+     * in extended class to receive this signal.
      *
      * See also:  ibus_input_context_set_capabilities().
      * <note><para>Argument @user_data is ignored in this function.</para></note>
@@ -509,7 +517,8 @@ ibus_engine_class_init (IBusEngineClass *class)
      * @engine: An IBusEngine.
      *
      * Emitted when the page-up button is pressed.
-     * Implement the member function page_up() in extended class to receive this signal.
+     * Implement the member function IBusEngineClass::page_up
+     * in extended class to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para></note>
      */
@@ -528,7 +537,8 @@ ibus_engine_class_init (IBusEngineClass *class)
      * @engine: An IBusEngine.
      *
      * Emitted when the page-down button is pressed.
-     * Implement the member function page_down() in extended class to receive this signal.
+     * Implement the member function IBusEngineClass::page_down
+     * in extended class to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para></note>
      */
@@ -547,7 +557,8 @@ ibus_engine_class_init (IBusEngineClass *class)
      * @engine: An IBusEngine.
      *
      * Emitted when the up cursor button is pressed.
-     * Implement the member function cursor_up() in extended class to receive this signal.
+     * Implement the member function IBusEngineClass::cursor_up
+     * in extended class to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para></note>
      */
@@ -566,7 +577,8 @@ ibus_engine_class_init (IBusEngineClass *class)
      * @engine: An IBusEngine.
      *
      * Emitted when the down cursor button is pressed.
-     * Implement the member function cursor_down() in extended class to receive this signal.
+     * Implement the member function IBusEngineClass::cursor_down
+     * in extended class to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para></note>
      */
@@ -588,7 +600,8 @@ ibus_engine_class_init (IBusEngineClass *class)
      * @state:  Keyboard state.
      *
      * Emitted when candidate on lookup table is clicked.
-     * Implement the member function candidate_clicked() in extended class to receive this signal.
+     * Implement the member function IBusEngineClass::candidate_clicked
+     * in extended class to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para></note>
      */
@@ -612,7 +625,8 @@ ibus_engine_class_init (IBusEngineClass *class)
      * @state:  Property state.
      *
      * Emitted when a property is activated or change changed.
-     * Implement the member function property_activate() in extended class to receive this signal.
+     * Implement the member function IBusEngineClass::property_activate
+     * in extended class to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para></note>
      */
@@ -634,7 +648,8 @@ ibus_engine_class_init (IBusEngineClass *class)
      * @name:   Property name.
      *
      * Emitted when a property is shown.
-     * Implement the member function property_side() in extended class to receive this signal.
+     * Implement the member function IBusEngineClass::property_side
+     * in extended class to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para></note>
      */
@@ -655,7 +670,8 @@ ibus_engine_class_init (IBusEngineClass *class)
      * @name:   Property name.
      *
      * Emitted when a property is hidden.
-     * Implement the member function property_hide() in extended class to receive this signal.
+     * Implement the member function IBusEngineClass::property_hide
+     * in extended class to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para></note>
      */
@@ -677,7 +693,8 @@ ibus_engine_class_init (IBusEngineClass *class)
      * @coordinates_len: The number of elements in the array.
      *
      * Emitted when a hand writing operation is cancelled.
-     * Implement the member function cancel_hand_writing() in extended class to receive this signal.
+     * Implement the member function IBusEngineClass::cancel_hand_writing
+     * in extended class to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para></note>
      */
@@ -699,7 +716,8 @@ ibus_engine_class_init (IBusEngineClass *class)
      * @n_strokes: The number of strokes to be removed. 0 means "remove all".
      *
      * Emitted when a hand writing operation is cancelled.
-     * Implement the member function cancel_hand_writing() in extended class to receive this signal.
+     * Implement the member function IBusEngineClass::cancel_hand_writing
+     * in extended class to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para></note>
      */
@@ -722,9 +740,10 @@ ibus_engine_class_init (IBusEngineClass *class)
      * @anchor_pos: The anchor position on selection area.
      *
      * Emitted when a surrounding text is set.
-     * Implement the member function set_surrounding_text() in extended class to receive this signal.
-     * If anchor_pos equals to cursor_pos, it means "there are no selection" or "does not support
-     * selection retrival".
+     * Implement the member function IBusEngineClass::set_surrounding_text
+     * in extended class to receive this signal.
+     * If anchor_pos equals to cursor_pos, it means "there are no selection"
+     * or "does not support selection retrival".
      *
      * <note><para>Argument @user_data is ignored in this function.</para></note>
      */
@@ -750,8 +769,8 @@ ibus_engine_class_init (IBusEngineClass *class)
      * Emitted when the client application content-type (primary
      * purpose and hints) is set.  The engine could change the
      * behavior according to the content-type.  Implement the member
-     * function set_content_type() in extended class to receive this
-     * signal.
+     * function IBusEngineClass::set_content_type
+     * in extended class to receive this signal.
      *
      * For example, if the client application wants to restrict input
      * to numbers, this signal will be emitted with @purpose set to
diff --git a/src/ibusengine.h b/src/ibusengine.h
index e77fdb27..b6461ce9 100644
--- a/src/ibusengine.h
+++ b/src/ibusengine.h
@@ -74,8 +74,6 @@ typedef struct _IBusEnginePrivate IBusEnginePrivate;
  * @has_focus: Whether the engine has focus.
  * @cursor_area: Area of cursor.
  * @client_capabilities: IBusCapabilite (client capabilities) flags.
- * @client_purpose: IBusInputPurpose (client input purpose).
- * @client_hints: IBusInputHints (client input hints) flags.
  *
  * IBusEngine properties.
  */
@@ -168,9 +166,10 @@ GType        ibus_engine_get_type       (void);
  * @engine_name: Name of the IBusObject.
  * @object_path: Path for IBusService.
  * @connection: An opened GDBusConnection.
- * @returns: A newly allocated IBusEngine.
  *
- * New an IBusEngine.
+ * Create a new #IBusEngine.
+ *
+ * Returns: A newly allocated IBusEngine.
  */
 IBusEngine  *ibus_engine_new            (const gchar        *engine_name,
                                          const gchar        *object_path,
@@ -181,9 +180,10 @@ IBusEngine  *ibus_engine_new            (const gchar        *engine_name,
  * @engine_name: Name of the IBusObject.
  * @object_path: Path for IBusService.
  * @connection: An opened GDBusConnection.
- * @returns: A newly allocated IBusEngine.
  *
- * New an IBusEngine.
+ * Create a new #IBusEngine.
+ *
+ * Returns: A newly allocated IBusEngine.
  */
 IBusEngine  *ibus_engine_new_with_type  (GType               engine_type,
                                          const gchar        *engine_name,
@@ -456,9 +456,10 @@ void ibus_engine_get_content_type       (IBusEngine         *engine,
 /**
  * ibus_engine_get_name:
  * @engine: An IBusEngine.
- * @returns: Name of IBusEngine.
  *
- * Return the name of IBusEngine.
+ * Return the name of #IBusEngine.
+ *
+ * Returns: Name of #IBusEngine.
  */
 const gchar *ibus_engine_get_name       (IBusEngine         *engine);
 
diff --git a/src/ibusenginedesc.h b/src/ibusenginedesc.h
index cafc4cae..45ec06bf 100644
--- a/src/ibusenginedesc.h
+++ b/src/ibusenginedesc.h
@@ -78,24 +78,6 @@ typedef struct _IBusEngineDescClass IBusEngineDescClass;
  *
  * Input method engine description data.
  * You can get extended values with g_object_get_properties.
- * 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
- * layout_variant: Keyboard variant
- * layout_option: Keyboard option
- * rank: Preference rank among engines, the highest ranked IME will put in
- * the front.
- * hotkeys: One or more hotkeys for switching to this engine, separated by
- *  semi-colon.
- * setup: Exec lists of the engine setup command.
- * version: Version number of the input method engine.
- * textdomain: Domain name for dgettext()
- * icon_prop_key: Key of IBusProperty to change panel icon dynamically.
  */
 struct _IBusEngineDesc {
     IBusSerializable parent;
@@ -123,9 +105,10 @@ GType            ibus_engine_desc_get_type      (void);
  * @author: Author of the input method engine.
  * @icon: Icon file of this engine.
  * @layout: Keyboard layout
- * @returns: A newly allocated IBusEngineDesc.
  *
- * New a IBusEngineDesc.
+ * Creates a new #IBusEngineDesc.
+ *
+ * Returns: A newly allocated IBusEngineDesc.
  */
 IBusEngineDesc  *ibus_engine_desc_new           (const gchar    *name,
                                                  const gchar    *longname,
@@ -139,12 +122,14 @@ IBusEngineDesc  *ibus_engine_desc_new           (const gchar    *name,
 /**
  * ibus_engine_desc_new_varargs:
  * @first_property_name: Name of the first property.
- * @Varargs: the NULL-terminated arguments of the properties and values.
+ * @...: the NULL-terminated arguments of the properties and values.
  *
- * New a IBusEngineDesc.
+ * Creates a new #IBusEngineDesc.
  * ibus_engine_desc_new_varargs() supports the va_list format.
  * name property is required. e.g.
  * ibus_engine_desc_new_varargs("name", "ibus-foo", "language", "us", NULL)
+ *
+ * Returns: A newly allocated IBusEngineDesc.
  */
 IBusEngineDesc  *ibus_engine_desc_new_varargs   (const gchar *first_property_name,
                                                  ...);
@@ -153,40 +138,44 @@ IBusEngineDesc  *ibus_engine_desc_new_varargs   (const gchar *first_property_nam
 /**
  * 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.
+ * Creates a new 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>
+ *
+ * Returns: A newly allocated IBusEngineDesc that contains description from
+ * @node.
  */
 IBusEngineDesc  *ibus_engine_desc_new_from_xml_node
                                                 (XMLNode        *node);
 /**
  * ibus_engine_desc_get_name:
  * @info: An IBusEngineDesc
- * @returns: name property in IBusEngineDesc
  *
- * Return the name property in IBusEngineDesc. It should not be freed.
+ * Gets the name property in IBusEngineDesc. It should not be freed.
+ *
+ * Returns: name property in IBusEngineDesc
  */
 const gchar     *ibus_engine_desc_get_name      (IBusEngineDesc *info);
 
 /**
  * ibus_engine_desc_get_longname:
  * @info: An IBusEngineDesc
- * @returns: longname property in IBusEngineDesc
  *
- * Return the longname property in IBusEngineDesc. It should not be freed.
+ * Gets the longname property in IBusEngineDesc. It should not be freed.
+ *
+ * Returns: longname property in IBusEngineDesc
  */
 const gchar     *ibus_engine_desc_get_longname  (IBusEngineDesc *info);
 
 /**
  * ibus_engine_desc_get_description:
  * @info: An IBusEngineDesc
- * @returns: description property in IBusEngineDesc
  *
- * Return the description property in IBusEngineDesc. It should not be freed.
+ * Gets the description property in IBusEngineDesc. It should not be freed.
+ *
+ * Returns: description property in IBusEngineDesc
  */
 const gchar     *ibus_engine_desc_get_description
                                                 (IBusEngineDesc *info);
@@ -194,54 +183,61 @@ const gchar     *ibus_engine_desc_get_description
 /**
  * ibus_engine_desc_get_language:
  * @info: An IBusEngineDesc
- * @returns: language property in IBusEngineDesc
  *
- * Return the language property in IBusEngineDesc. It should not be freed.
+ * Gets the language property in IBusEngineDesc. It should not be freed.
+ *
+ * Returns: language property in IBusEngineDesc
  */
 const gchar     *ibus_engine_desc_get_language  (IBusEngineDesc *info);
 
+
 /**
  * ibus_engine_desc_get_license:
  * @info: An IBusEngineDesc
- * @returns: license property in IBusEngineDesc
  *
- * Return the license property in IBusEngineDesc. It should not be freed.
+ * Gets the license property in IBusEngineDesc. It should not be freed.
+ *
+ * Returns: license property in IBusEngineDesc
  */
 const gchar     *ibus_engine_desc_get_license   (IBusEngineDesc *info);
 
 /**
  * ibus_engine_desc_get_author:
  * @info: An IBusEngineDesc
- * @returns: author property in IBusEngineDesc
  *
- * Return the author property in IBusEngineDesc. It should not be freed.
+ * Gets the author property in IBusEngineDesc. It should not be freed.
+ *
+ * Returns: author property in IBusEngineDesc
  */
 const gchar     *ibus_engine_desc_get_author    (IBusEngineDesc *info);
 
 /**
  * ibus_engine_desc_get_icon:
  * @info: An IBusEngineDesc
- * @returns: icon property in IBusEngineDesc
  *
- * Return the icon property in IBusEngineDesc. It should not be freed.
+ * Gets the icon property in IBusEngineDesc. It should not be freed.
+ *
+ * Returns: icon property in IBusEngineDesc
  */
 const gchar     *ibus_engine_desc_get_icon      (IBusEngineDesc *info);
 
 /**
  * ibus_engine_desc_get_layout:
  * @info: An IBusEngineDesc
- * @returns: layout property in IBusEngineDesc
  *
- * Return the layout property in IBusEngineDesc. It should not be freed.
+ * Gets the layout property in IBusEngineDesc. It should not be freed.
+ *
+ * Returns: layout property in IBusEngineDesc
  */
 const gchar     *ibus_engine_desc_get_layout    (IBusEngineDesc *info);
 
 /**
  * ibus_engine_desc_get_layout_variant:
  * @info: An IBusEngineDesc
- * @returns: keyboard variant property in IBusEngineDesc
  *
- * Return the keyboard variant property in IBusEngineDesc. It should not be freed.
+ * Gets the keyboard variant property in IBusEngineDesc. It should not be freed.
+ *
+ * Returns: keyboard variant property in IBusEngineDesc
  */
 const gchar     *ibus_engine_desc_get_layout_variant
                                                 (IBusEngineDesc *info);
@@ -249,9 +245,10 @@ const gchar     *ibus_engine_desc_get_layout_variant
 /**
  * ibus_engine_desc_get_layout_option:
  * @info: An IBusEngineDesc
- * @returns: keyboard option property in IBusEngineDesc
  *
- * Return the keyboard option property in IBusEngineDesc. It should not be freed.
+ * Gets the keyboard option property in IBusEngineDesc. It should not be freed.
+ *
+ * Returns: keyboard option property in IBusEngineDesc
  */
 const gchar     *ibus_engine_desc_get_layout_option
                                                 (IBusEngineDesc *info);
@@ -259,54 +256,60 @@ const gchar     *ibus_engine_desc_get_layout_option
 /**
  * ibus_engine_desc_get_rank:
  * @info: An IBusEngineDesc
- * @returns: rank property in IBusEngineDesc
  *
- * Return the rank property in IBusEngineDesc.
+ * Gets the rank property in IBusEngineDesc.
+ *
+ * Returns: rank property in IBusEngineDesc
  */
 guint            ibus_engine_desc_get_rank      (IBusEngineDesc *info);
 
 /**
  * ibus_engine_desc_get_hotkeys:
  * @info: An IBusEngineDesc
- * @returns: hotkeys property in IBusEngineDesc
  *
- * Return the hotkeys property in IBusEngineDesc. It should not be freed.
+ * Gets the hotkeys property in IBusEngineDesc. It should not be freed.
+ *
+ * Returns: hotkeys property in IBusEngineDesc
  */
 const gchar     *ibus_engine_desc_get_hotkeys   (IBusEngineDesc *info);
 
 /**
  * ibus_engine_desc_get_symbol:
  * @info: An IBusEngineDesc
- * @returns: symbol property in IBusEngineDesc
  *
- * Return the symbol property in IBusEngineDesc. It should not be freed.
+ * Gets the symbol property in IBusEngineDesc. It should not be freed.
+ *
+ * Returns: symbol property in IBusEngineDesc
  */
 const gchar     *ibus_engine_desc_get_symbol    (IBusEngineDesc *info);
 
 /**
  * ibus_engine_desc_get_setup:
  * @info: An IBusEngineDesc
- * @returns: setup property in IBusEngineDesc
  *
- * Return the setup property in IBusEngineDesc. It should not be freed.
+ * Gets the setup property in IBusEngineDesc. It should not be freed.
+ *
+ * Returns: setup property in IBusEngineDesc
  */
 const gchar     *ibus_engine_desc_get_setup     (IBusEngineDesc *info);
 
 /**
  * ibus_engine_desc_get_version:
  * @info: An IBusEngineDesc
- * @returns: version in IBusEngineDesc
  *
- * Return the version property in IBusEngineDesc. It should not be freed.
+ * Gets the version property in IBusEngineDesc. It should not be freed.
+ *
+ * Returns: version in IBusEngineDesc
  */
 const gchar     *ibus_engine_desc_get_version   (IBusEngineDesc *info);
 
 /**
  * ibus_engine_desc_get_textdomain:
  * @info: An IBusEngineDesc
- * @returns: textdomain in IBusEngineDesc
  *
- * Return the textdomain property in IBusEngineDesc. It should not be freed.
+ * Gets the textdomain property in IBusEngineDesc. It should not be freed.
+ *
+ * Returns: textdomain in IBusEngineDesc
  */
 const gchar     *ibus_engine_desc_get_textdomain
                                                 (IBusEngineDesc *info);
@@ -314,10 +317,11 @@ const gchar     *ibus_engine_desc_get_textdomain
 /**
  * ibus_engine_desc_get_icon_prop_key:
  * @info: An IBusEngineDesc
- * @returns: IBusProperty.key for dynamic panel icon in IBusEngineDesc
  *
- * Return the key of IBusProperty to load the panel icon dynamically
-   in IBusEngineDesc. It should not be freed.
+ * Gets the key of IBusProperty to load the panel icon dynamically
+ * in IBusEngineDesc. It should not be freed.
+ *
+ * Returns: IBusProperty.key for dynamic panel icon in IBusEngineDesc
  */
 const gchar     *ibus_engine_desc_get_icon_prop_key
                                                 (IBusEngineDesc *info);
diff --git a/src/ibusenginesimple.h b/src/ibusenginesimple.h
index 76d46f4b..c74928ae 100644
--- a/src/ibusenginesimple.h
+++ b/src/ibusenginesimple.h
@@ -28,7 +28,7 @@
 #define __IBUS_ENGINE_SIMPLE_H__
 
 /**
- * SECTION: ibussimpleengine
+ * SECTION: ibusenginesimple
  * @short_description: Input method engine supporting table-based input method
  * @title: IBusEngineSimple
  * @stability: Stable
@@ -102,6 +102,7 @@ GType   ibus_engine_simple_get_type       (void);
  *      during the whole life of the simple engine.
  * @max_seq_len: Maximum length of a swquence in the table (cannot be greater
  *      than %IBUS_MAX_COMPOSE_LEN)
+ * @n_seqs: number of sequences in the table
  *
  * Adds an additional table to search to the engine. Each row of the table
  * consists of max_seq_len key symbols followed by two guint16 interpreted as
@@ -121,9 +122,10 @@ void             ibus_engine_simple_add_table   (IBusEngineSimple  *simple,
  * @simple: An IBusEngineSimple.
  * @locale: (allow-none): The locale name. If the locale is %NULL,
  *                        the current locale is used.
- * @returns: %TRUE if the @locale is matched to the table.
  *
  * Call ibus_engine_simple_add_table() internally by locale.
+ *
+ * Returns: %TRUE if the @locale is matched to the table.
  */
 gboolean         ibus_engine_simple_add_table_by_locale
                                                 (IBusEngineSimple  *simple,
@@ -134,9 +136,10 @@ gboolean         ibus_engine_simple_add_table_by_locale
  * @simple: An IBusEngineSimple.
  * @file: The compose file. If the @file is %NULL,
  *        the current locale is used.
- * @returns: %TRUE if the @file is loaded.
  *
  * Call ibus_engine_simple_add_table() internally by locale.
+ *
+ * Returns: %TRUE if the @file is loaded.
  */
 gboolean         ibus_engine_simple_add_compose_file
                                                 (IBusEngineSimple  *simple,
diff --git a/src/ibusenumtypes.h.template b/src/ibusenumtypes.h.template
index 3ad38980..6a754b66 100644
--- a/src/ibusenumtypes.h.template
+++ b/src/ibusenumtypes.h.template
@@ -2,14 +2,6 @@
 #ifndef __IBUS_ENUM_TYPES_H__
 #define __IBUS_ENUM_TYPES_H__
 
-/**
- * SECTION: ibusenumtypes
- * @short_description: Enumeration definition in IBus.
- * @stability: Stable
- *
- * IBusEnumTypes lists IBus enumeration types.
- */
-
 #include <glib-object.h>
 
 G_BEGIN_DECLS
diff --git a/src/ibusfactory.h b/src/ibusfactory.h
index 80691833..912f5d5e 100644
--- a/src/ibusfactory.h
+++ b/src/ibusfactory.h
@@ -142,18 +142,20 @@ struct _IBusFactoryClass {
 
 /**
  * ibus_factory_info_get_type:
- * @returns: GType of IBus factory information.
  *
- * Return GType of IBus factory information.
+ * Gets GType of IBus factory information.
+ *
+ * Returns: GType of IBus factory information.
  */
 GType            ibus_factory_get_type          (void);
 
 /**
  * ibus_factory_new:
  * @connection: An GDBusConnection.
- * @returns: A newly allocated IBusFactory.
  *
- * New an IBusFactory.
+ * Creates a new #IBusFactory.
+ *
+ * Returns: A newly allocated #IBusFactory.
  */
 IBusFactory     *ibus_factory_new               (GDBusConnection *connection);
 
@@ -173,9 +175,10 @@ void             ibus_factory_add_engine        (IBusFactory    *factory,
  * ibus_factory_create_engine:
  * @factory: An #IBusFactory.
  * @engine_name: Name of an engine.
- * @returns: (transfer full): #IBusEngine with @engine_name.
  *
- * Create an #IBusEngine with @engine_name.
+ * Creates an #IBusEngine with @engine_name.
+ *
+ * Returns: (transfer full): #IBusEngine with @engine_name.
  */
 IBusEngine      *ibus_factory_create_engine     (IBusFactory    *factory,
                                                  const gchar    *engine_name);
diff --git a/src/ibushotkey.h b/src/ibushotkey.h
index 9f985eb7..8153036f 100644
--- a/src/ibushotkey.h
+++ b/src/ibushotkey.h
@@ -82,9 +82,10 @@ struct _IBusHotkeyProfileClass {
 GType            ibus_hotkey_profile_get_type   (void);
 /**
  * ibus_hotkey_profile_new:
- * @returns: A newly allocated IBusHotkeyProfile.
  *
- * New an IBusHotkeyProfile.
+ * Creates a new #IBusHotkeyProfile.
+ *
+ * Returns: A newly allocated #IBusHotkeyProfile.
  */
 IBusHotkeyProfile
                 *ibus_hotkey_profile_new        (void);
@@ -95,9 +96,10 @@ IBusHotkeyProfile
  * @keyval: Keycode of the hotkey.
  * @modifiers: Modifiers of the hotkey.
  * @event: The event to be associated.
- * @returns: Always TRUE.
  *
- * Add a hotkey and its associated event to an IBusHotkeyProfile.
+ * Adds a hotkey and its associated event to an #IBusHotkeyProfile.
+ *
+ * Returns: Always %TRUE.
  */
 gboolean         ibus_hotkey_profile_add_hotkey (IBusHotkeyProfile  *profile,
                                                  guint               keyval,
@@ -109,10 +111,12 @@ gboolean         ibus_hotkey_profile_add_hotkey (IBusHotkeyProfile  *profile,
  * @profile: An IBusHotkeyProfile.
  * @str: Key in string representation.  '+' is the separator.
  * @event: The event to be associated.
- * @returns: FALSE if @str contains invalid symbol; TRUE otherwise.
  *
- * Add a hotkey and its associated event to an IBusHotkeyProfile.
- * The hotkey is in string format, such like <constant>Control+Shift+A</constant>.
+ * Adds a hotkey and its associated event to an #IBusHotkeyProfile.
+ * The hotkey is in string format, such like
+ * <constant>Control+Shift+A</constant>.
+ *
+ * Returns: FALSE if @str contains invalid symbol; TRUE otherwise.
  */
 gboolean         ibus_hotkey_profile_add_hotkey_from_string
                                                 (IBusHotkeyProfile  *profile,
@@ -124,9 +128,10 @@ gboolean         ibus_hotkey_profile_add_hotkey_from_string
  * @profile: An IBusHotkeyProfile.
  * @keyval: Keycode of the hotkey.
  * @modifiers: Modifiers of the hotkey.
- * @returns: FALSE if the key is not in @profile, TRUE otherwise.
  *
- * Remove the hotkey for an IBusHotkeyProfile.
+ * Removes the hotkey for an #IBusHotkeyProfile.
+ *
+ * Returns: %FALSE if the key is not in @profile, %TRUE otherwise.
  */
 gboolean         ibus_hotkey_profile_remove_hotkey
                                                 (IBusHotkeyProfile  *profile,
@@ -137,9 +142,10 @@ gboolean         ibus_hotkey_profile_remove_hotkey
  * ibus_hotkey_profile_remove_hotkey_by_event:
  * @profile: An IBusHotkeyProfile.
  * @event: The associated event.
- * @returns: FALSE if no such event in @profile, TRUE otherwise.
  *
- * Remove the hotkey for an IBusHotkeyProfile by event.
+ * Removes the hotkey for an #IBusHotkeyProfile by event.
+ *
+ * Returns: %FALSE if no such event in @profile, %TRUE otherwise.
  */
 gboolean         ibus_hotkey_profile_remove_hotkey_by_event
                                                 (IBusHotkeyProfile  *profile,
@@ -153,9 +159,11 @@ gboolean         ibus_hotkey_profile_remove_hotkey_by_event
  * @prev_keyval: Keycode of the hotkey.
  * @prev_modifiers: Modifiers of the hotkey.
  * @user_data: user data for signal "trigger".
- * @returns: 0 if releasing a hotkey and the hotkey is not in the profile ; an associated event otherwise.
  *
- * Emit a <constant>::trigger</constant> signal when a hotkey is in a profile.
+ * Emits a <constant>::trigger</constant> signal when a hotkey is in a profile.
+ *
+ * Returns: 0 if releasing a hotkey and the hotkey is not in the profile;
+ * an associated event otherwise.
  *
  * See also: ::trigger
  */
@@ -172,7 +180,8 @@ GQuark           ibus_hotkey_profile_filter_key_event
  * @profile: An IBusHotkeyProfile.
  * @keyval: Keycode of the hotkey.
  * @modifiers: Modifiers of the hotkey.
- * @returns: The event associated to the hotkey or 0 if the hotkey is not in the
+ *
+ * Returns: The event associated to the hotkey or 0 if the hotkey is not in the
  * profile.
  */
 GQuark           ibus_hotkey_profile_lookup_hotkey
diff --git a/src/ibusinputcontext.h b/src/ibusinputcontext.h
index 0fd6ef88..5c6372f6 100644
--- a/src/ibusinputcontext.h
+++ b/src/ibusinputcontext.h
@@ -90,12 +90,13 @@ GType        ibus_input_context_get_type    (void);
 /**
  * ibus_input_context_new:
  * @path: The path to the object that emitting the signal.
- * @connection: An #GDBusConnection.
+ * @connection: A #GDBusConnection.
  * @cancellable: A #GCancellable or %NULL.
  * @error: Return location for error or %NULL.
- * @returns: A newly allocated IBusInputContext.
  *
- * New an IBusInputContext.
+ * Creates a new #IBusInputContext.
+ *
+ * Returns: A newly allocated #IBusInputContext.
  */
 IBusInputContext *
              ibus_input_context_new         (const gchar        *path,
@@ -105,13 +106,13 @@ IBusInputContext *
 /**
  * ibus_input_context_new_async:
  * @path: The path to the object that emitting the signal.
- * @connection: An #GDBusConnection.
+ * @connection: A #GDBusConnection.
  * @cancellable: A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
  *      The callback should not be %NULL.
  * @user_data: The data to pass to callback.
  *
- * New an #IBusInputContext asynchronously.
+ * Creates a new #IBusInputContext asynchronously.
  */
 void         ibus_input_context_new_async   (const gchar        *path,
                                              GDBusConnection    *connection,
@@ -124,9 +125,10 @@ void         ibus_input_context_new_async   (const gchar        *path,
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback pass to
  *      ibus_input_context_new_async().
  * @error: Return location for error or %NULL.
- * @returns: A newly allocated #IBusInputContext.
  *
  * Finishes an operation started with ibus_input_context_new_async().
+ *
+ * Returns: A newly allocated #IBusInputContext.
  */
 IBusInputContext *
              ibus_input_context_new_async_finish
@@ -135,10 +137,11 @@ IBusInputContext *
 /**
  * ibus_input_context_get_input_context:
  * @path: The path to the object that emitting the signal.
- * @connection: An #GDBusConnection.
- * @returns: (transfer none): An existing #IBusInputContext.
+ * @connection: A GDBusConnection.
  *
  * Gets an existing IBusInputContext.
+ *
+ * Returns: (transfer none): An existing #IBusInputContext.
  */
 IBusInputContext *
              ibus_input_context_get_input_context
@@ -147,13 +150,13 @@ IBusInputContext *
 /**
  * ibus_input_context_get_input_context_async:
  * @path: The path to the object that emitting the signal.
- * @connection: An #GDBusConnection.
+ * @connection: A #GDBusConnection.
  * @cancellable: A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
  *      The callback should not be %NULL.
  * @user_data: The data to pass to callback.
  *
- * Get an existing #IBusInputContext asynchronously.
+ * Gets an existing #IBusInputContext asynchronously.
  */
 void         ibus_input_context_get_input_context_async
                                             (const gchar        *path,
@@ -167,9 +170,11 @@ void         ibus_input_context_get_input_context_async
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback pass to
  *      ibus_input_context_get_input_context_async().
  * @error: Return location for error or %NULL.
- * @returns: (transfer none): An existing #IBusInputContext.
  *
- * Finishes an operation started with ibus_input_contex_get_input_context_async().
+ * Finishes an operation started with
+ * ibus_input_context_get_input_context_async().
+ *
+ * Returns: (transfer none): An existing #IBusInputContext.
  */
 IBusInputContext *
              ibus_input_context_get_input_context_async_finish
@@ -256,14 +261,16 @@ void        ibus_input_context_process_key_event_async
 
 /**
  * ibus_input_context_process_key_event_async_finish:
- * @context: An IBusInputContext.
- * @res: A GAsyncResult obtained from the GAsyncReadyCallback passed to
+ * @context: An #IBusInputContext.
+ * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *      ibus_input_context_process_key_event_async().
- * @error: Return location for error or NULL.
- * @returns: %TRUE if the key event is processed;
- *      %FALSE otherwise or some errors happen and the @error will be set.
+ * @error: Return location for error or %NULL.
  *
- * Finishes an operation started with ibus_input_context_process_key_event_async().
+ * Finishes an operation started with
+ *      ibus_input_context_process_key_event_async().
+ *
+ * Returns: %TRUE if the key event is processed;
+ *      %FALSE otherwise or some errors happen and the @error will be set.
  */
 gboolean     ibus_input_context_process_key_event_async_finish
                                             (IBusInputContext   *context,
@@ -272,13 +279,15 @@ gboolean     ibus_input_context_process_key_event_async_finish
 
 /**
  * ibus_input_context_process_key_event:
- * @context: An IBusInputContext.
+ * @context: An #IBusInputContext.
  * @keyval: Key symbol of a key event.
  * @keycode: Keycode of a key event.
  * @state: Key modifier flags.
- * @returns: TRUE for successfully process the key; FALSE otherwise.
  *
- * Pass the key event to input method engine and wait for the reply from ibus (i.e. synchronous IPC).
+ * Pass the key event to input method engine and wait for the reply from
+ * ibus (i.e. synchronous IPC).
+ *
+ * Returns: %TRUE for successfully process the key; %FALSE otherwise.
  *
  * See also: ibus_input_context_process_key_event_async()
  */
@@ -324,7 +333,7 @@ void         ibus_input_context_set_capabilities
 
 /**
  * ibus_input_context_property_activate:
- * @context: An IBusInputContext.
+ * @context: An #IBusInputContext.
  * @prop_name: A property name (e.g. "InputMode.WideLatin")
  * @state: A status of the property (e.g. PROP_STATE_CHECKED)
  *
@@ -339,9 +348,10 @@ void         ibus_input_context_property_activate
 
 /**
  * ibus_input_context_focus_in:
- * @context: An IBusInputContext.
+ * @context: An #IBusInputContext.
  *
- * Invoked when the client application get focus. An asynchronous IPC will be performed.
+ * Invoked when the client application get focus. An asynchronous IPC will
+ * be performed.
  *
  * see_also: #IBusEngine::focus_in.
  */
@@ -349,7 +359,7 @@ void         ibus_input_context_focus_in    (IBusInputContext   *context);
 
 /**
  * ibus_input_context_focus_out:
- * @context: An IBusInputContext.
+ * @context: An #IBusInputContext.
  *
  * Invoked when the client application get focus. An asynchronous IPC will be performed.
  *
@@ -360,7 +370,7 @@ void         ibus_input_context_focus_out   (IBusInputContext   *context);
 
 /**
  * ibus_input_context_reset:
- * @context: An IBusInputContext.
+ * @context: An #IBusInputContext.
  *
  * Invoked when the IME is reset. An asynchronous IPC will be performed.
  *
@@ -373,8 +383,8 @@ void         ibus_input_context_reset       (IBusInputContext   *context);
  * @context: An #IBusInputContext.
  * @timeout_msec: The timeout in milliseconds or -1 to use the default timeout.
  * @cancellable: A #GCancellable or %NULL.
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL
- *      if you don't care about the result of the method invocation.
+ * @callback: A #GAsyncReadyCallback to call when the request is satisfied or
+ *     %NULL if you don't care about the result of the method invocation.
  * @user_data: The data to pass to callback.
  *
  * An asynchronous IPC will be performed.
@@ -392,9 +402,11 @@ void         ibus_input_context_get_engine_async
  * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to
  *   ibus_input_context_get_engine_async().
  * @error: Return location for error or %NULL.
- * @returns: (transfer none): An IME engine description for the context, or %NULL.
  *
  * Finishes an operation started with ibus_input_context_get_engine_async().
+ *
+ * Returns: (transfer none): An IME engine description for the context, or
+ *     %NULL.
  */
 IBusEngineDesc *
              ibus_input_context_get_engine_async_finish
@@ -404,18 +416,19 @@ IBusEngineDesc *
 
 /**
  * ibus_input_context_get_engine:
- * @context: An IBusInputContext.
- * @returns: (transfer none): An IME engine description for the context, or NULL.
+ * @context: An #IBusInputContext.
  *
- * Returns an IME engine description for the context.
+ * Gets an IME engine description for the context.
  * A synchronous IPC will be performed.
+ *
+ * Returns: (transfer none): An IME engine description for the context, or NULL.
  */
 IBusEngineDesc *
              ibus_input_context_get_engine  (IBusInputContext   *context);
 
 /**
  * ibus_input_context_set_engine:
- * @context: An IBusInputContext.
+ * @context: An #IBusInputContext.
  * @name: A name of the engine.
  *
  * Invoked when the IME engine is changed.
@@ -440,10 +453,11 @@ void         ibus_input_context_set_surrounding_text
 /**
  * ibus_input_context_needs_surrounding_text:
  * @context: An #IBusInputContext.
- * @returns: %TRUE if surrounding-text is needed by the current engine;
- * %FALSE otherwise.
  *
  * Check whether the current engine requires surrounding-text.
+ *
+ * Returns: %TRUE if surrounding-text is needed by the current engine;
+ * %FALSE otherwise.
  */
 gboolean     ibus_input_context_needs_surrounding_text
                                             (IBusInputContext   *context);
diff --git a/src/ibusinternal.h b/src/ibusinternal.h
index 49dc5646..c2637ab5 100644
--- a/src/ibusinternal.h
+++ b/src/ibusinternal.h
@@ -24,15 +24,6 @@
 #error "Only <ibus.h> can be included directly"
 #endif
 
-/**
- * SECTION: ibusinternal
- * @short_description: IBus internal.
- * @title: IBusInternal
- * @stability: Stable
- *
- * This section contain several IBus house keeping functions.
- *
- */
 #ifndef __IBUS_INTERNEL_H_
 #define __IBUS_INTERNEL_H_
 
diff --git a/src/ibuskeymap.h b/src/ibuskeymap.h
index 2f662731..7f079ef9 100644
--- a/src/ibuskeymap.h
+++ b/src/ibuskeymap.h
@@ -113,13 +113,14 @@ GType            ibus_keymap_get_type               (void);
 /**
  * ibus_keymap_new:
  * @name: The keymap file to be loaded, such as 'us', 'jp'.
- * @returns: An IBusKeymap associated with the giving name; or NULL if failed.
  *
- * Get an IBusKeymap associated with the giving name.
+ * Get an #IBusKeymap associated with the giving name.
  *
  * This function loads the keymap file specified in @name
  * in the IBUS_DATA_DIR/keymaps directory.
  *
+ * Returns: An #IBusKeymap associated with the giving name; or %NULL if failed.
+ *
  * Deprecated: This function has been deprecated and should
  * not be used in newly written code. Please use ibus_keymap_get().
  */
@@ -129,13 +130,14 @@ IBusKeymap        *ibus_keymap_new                  (const gchar        *name)
 /**
  * ibus_keymap_get:
  * @name: The keymap file to be loaded, such as 'us', 'jp'.
- * @returns: (transfer full): An IBusKeymap associated with the giving name;
- * or %NULL if failed.
  *
  * Get an IBusKeymap associated with the giving name.
  *
  * This function loads the keymap file specified in @name
  * in the IBUS_DATA_DIR/keymaps directory.
+ *
+ * Returns: (transfer full): An #IBusKeymap associated with the giving name;
+ * or %NULL if failed.
  */
 IBusKeymap        *ibus_keymap_get                  (const gchar        *name);
 
@@ -144,9 +146,10 @@ IBusKeymap        *ibus_keymap_get                  (const gchar        *name);
  * @keymap: An IBusKeymap.
  * @keycode: A scancode to be converted.
  * @state: Modifier flags(such as Ctrl, Shift).
- * @returns: Corresponding keysym.
  *
- * Convert the scancode to keysym, given the keymap.
+ * Converts the scancode to keysym, given the keymap.
+ *
+ * Returns: Corresponding keysym.
  */
 guint              ibus_keymap_lookup_keysym        (IBusKeymap         *keymap,
                                                      guint16             keycode,
diff --git a/src/ibuskeys.h b/src/ibuskeys.h
index 6ad0a903..74c23a68 100644
--- a/src/ibuskeys.h
+++ b/src/ibuskeys.h
@@ -33,20 +33,22 @@ G_BEGIN_DECLS
 /**
  * ibus_keyval_name:
  * @keyval: Key symbol.
- * @returns: Corresponding key name. %NULL if no such key symbol.
  *
  * Return the name of a key symbol.
  *
  * Note that the returned string is used internally, so don't free it.
+ *
+ * Returns: Corresponding key name. %NULL if no such key symbol.
  */
 const gchar     *ibus_keyval_name       (guint           keyval);
 
 /**
  * ibus_keyval_from_name:
  * @keyval_name: Key name in #gdk_keys_by_name.
- * @returns: Corresponding key symbol.
  *
  * Return the key symbol that associate with the key name.
+ *
+ * Returns: Corresponding key symbol.
  */
 guint            ibus_keyval_from_name  (const gchar    *keyval_name);
 
@@ -56,9 +58,9 @@ guint            ibus_keyval_from_name  (const gchar    *keyval_name);
  * 
  * Convert from a ISO10646 character to a key symbol.
  * 
- * Return value: the corresponding IBus key symbol, if one exists.
- *               or, if there is no corresponding symbol,
- *               wc | 0x01000000
+ * Returns: the corresponding IBus key symbol, if one exists.
+ *          or, if there is no corresponding symbol,
+ *          wc | 0x01000000
  **/
 guint            ibus_unicode_to_keyval (gunichar        wc);
 
@@ -69,8 +71,8 @@ guint            ibus_unicode_to_keyval (gunichar        wc);
  * Convert from an IBus key symbol to the corresponding ISO10646 (Unicode)
  * character.
  * 
- * Return value: the corresponding unicode character, or 0 if there
- *               is no corresponding character.
+ * Returns: the corresponding unicode character, or 0 if there
+ *          is no corresponding character.
  **/
 gunichar         ibus_keyval_to_unicode (guint           keyval);
 
@@ -103,7 +105,7 @@ guint            ibus_keyval_to_lower (guint keyval);
  * @upper: (out): return location for uppercase version of @symbol
  *
  * Obtains the upper- and lower-case versions of the keyval @symbol.
- * Examples of keyvals are #IBUS_KEY_a, #IBUS_KEY_Enter, #IBUS_KEY_F1, etc.
+ * Examples of keyvals are #IBUS_KEY_a, #IBUS_KEY_Return, #IBUS_KEY_F1, etc.
  */
 void ibus_keyval_convert_case (guint symbol, guint *lower, guint *upper);
 
diff --git a/src/ibuslookuptable.h b/src/ibuslookuptable.h
index 77124360..843e2e21 100644
--- a/src/ibuslookuptable.h
+++ b/src/ibuslookuptable.h
@@ -111,9 +111,10 @@ GType                ibus_lookup_table_get_type (void);
  * @cursor_pos: position index of cursor.
  * @cursor_visible: whether the cursor is visible.
  * @round: TRUE for lookup table wrap around.
- * @returns: A newly allocated IBusLookupTable.
  *
- * New a IBusLookupTable.
+ * Craetes a new #IBusLookupTable.
+ *
+ * Returns: A newly allocated #IBusLookupTable.
  */
 IBusLookupTable     *ibus_lookup_table_new      (guint               page_size,
                                                  guint               cursor_pos,
@@ -134,9 +135,10 @@ void                 ibus_lookup_table_append_candidate
 /**
  * ibus_lookup_table_get_number_of_candidates:
  * @table: An IBusLookupTable.
- * @returns: The number of candidates in the table
  *
  * Return the number of candidate in the table.
+ *
+ * Returns: The number of candidates in the table
  */
 guint               ibus_lookup_table_get_number_of_candidates
                                                 (IBusLookupTable    *table);
@@ -145,9 +147,11 @@ guint               ibus_lookup_table_get_number_of_candidates
  * ibus_lookup_table_get_candidate:
  * @table: An IBusLookupTable.
  * @index: Index in the Lookup table.
- * @returns: (transfer none): IBusText at the given index; NULL if no such IBusText.
  *
- * Return IBusText at the given index. Borrowed reference.
+ * Return #IBusText at the given index. Borrowed reference.
+ *
+ * Returns: (transfer none): IBusText at the given index; NULL if no such
+ *         #IBusText.
  */
 IBusText            *ibus_lookup_table_get_candidate
                                                 (IBusLookupTable    *table,
@@ -185,9 +189,11 @@ void                 ibus_lookup_table_set_label
  * ibus_lookup_table_get_label:
  * @table: An IBusLookupTable.
  * @index: Index in the Lookup table.
- * @returns: (transfer none): IBusText at the given index; NULL if no such IBusText.
  *
- * Return IBusText at the given index. Borrowed reference.
+ * Return #IBusText at the given index. Borrowed reference.
+ *
+ * Returns: (transfer none): #IBusText at the given index; %NULL if no such
+ *         #IBusText.
  */
 IBusText            *ibus_lookup_table_get_label
                                                 (IBusLookupTable    *table,
@@ -208,9 +214,10 @@ void                 ibus_lookup_table_set_cursor_pos
 /**
  * ibus_lookup_table_get_cursor_pos:
  * @table: An IBusLookupTable.
- * @returns: The position of cursor.
  *
- * Get the cursor position of IBusLookupTable.
+ * Gets the cursor position of #IBusLookupTable.
+ *
+ * Returns: The position of cursor.
  */
 guint                ibus_lookup_table_get_cursor_pos
                                                 (IBusLookupTable    *table);
@@ -228,10 +235,11 @@ void                 ibus_lookup_table_set_cursor_visible
 
 /**
  * ibus_lookup_table_is_cursor_visible:
- * @table: An IBusLookupTable.
- * @returns: Whether the cursor of @table is visible.
+ * @table: An #IBusLookupTable.
  *
- * Returns whether the cursor of an IBusLookupTable is visible.
+ * Returns whether the cursor of an #IBusLookupTable is visible.
+ *
+ * Returns: Whether the cursor of @table is visible.
  */
 gboolean             ibus_lookup_table_is_cursor_visible
                                                 (IBusLookupTable    *table);
@@ -239,9 +247,10 @@ gboolean             ibus_lookup_table_is_cursor_visible
 /**
  * ibus_lookup_table_get_cursor_in_page:
  * @table: An IBusLookupTable.
- * @returns: The position of cursor in current page.
  *
- * Get the cursor position in current page of IBusLookupTable.
+ * Gets the cursor position in current page of #IBusLookupTable.
+ *
+ * Returns: The position of cursor in current page.
  */
 guint                ibus_lookup_table_get_cursor_in_page
                                                 (IBusLookupTable    *table);
@@ -259,9 +268,11 @@ void                 ibus_lookup_table_set_page_size
 /**
  * ibus_lookup_table_get_page_size:
  * @table: An IBusLookupTable.
- * @returns: Page size, i.e., number of candidate shown per page.
  *
- * Get the number of candidate shown per page.
+ * Gets the number of candidate shown per page.
+ *
+ * Returns: Page size, i.e., number of candidate shown per page.
+dd
  */
 guint                ibus_lookup_table_get_page_size
                                                 (IBusLookupTable    *table);
@@ -279,9 +290,10 @@ void                 ibus_lookup_table_set_round
 /**
  * ibus_lookup_table_is_round:
  * @table: An IBusLookupTable.
- * @returns: Whether the @table is round.
  *
- * Returns whether the IBusLookupTable is round.
+ * Returns whether the #IBusLookupTable is round.
+ *
+ * Returns: Whether the @table is round.
  */
 gboolean             ibus_lookup_table_is_round (IBusLookupTable    *table);
 
@@ -299,9 +311,10 @@ void                 ibus_lookup_table_set_orientation
 /**
  * ibus_lookup_table_get_orientation:
  * @table: An IBusLookupTable.
- * @returns: The orientation of the @table.
  *
- * Returns the orientation of the IBusLookupTable.
+ * Returns the orientation of the #IBusLookupTable.
+ *
+ * Returns: The orientation of the @table.
  */
 gint                 ibus_lookup_table_get_orientation
                                                 (IBusLookupTable    *table);
@@ -318,52 +331,56 @@ void                 ibus_lookup_table_clear    (IBusLookupTable    *table);
 /**
  * ibus_lookup_table_page_up:
  * @table: An IBusLookupTable.
- * @returns: TRUE if succeed.
  *
- * Go to previous page of an IBusLookupTable.
+ * Go to previous page of an #IBusLookupTable.
  *
  * It returns FALSE if it is already at the first page,
  * unless  <code>table&gt;-round==TRUE</code>, where it will go
  * to the last page.
+ *
+ * Returns: %TRUE if succeed.
  */
 gboolean             ibus_lookup_table_page_up  (IBusLookupTable    *table);
 
 /**
  * ibus_lookup_table_page_down:
  * @table: An IBusLookupTable.
- * @returns: TRUE if succeed.
  *
- * Go to next page of an IBusLookupTable.
+ * Go to next page of an #IBusLookupTable.
  *
  * It returns FALSE if it is already at the last page,
  * unless  <code>table&gt;-round==TRUE</code>, where it will go
  * to the first page.
+ *
+ * Returns: %TRUE if succeed.
  */
 gboolean             ibus_lookup_table_page_down(IBusLookupTable    *table);
 
 /**
  * ibus_lookup_table_cursor_up:
  * @table: An IBusLookupTable.
- * @returns: TRUE if succeed.
  *
- * Go to previous candidate of an IBusLookupTable.
+ * Go to previous candidate of an #IBusLookupTable.
  *
  * It returns FALSE if it is already at the first candidate,
  * unless  <code>table&gt;-round==TRUE</code>, where it will go
  * to the last candidate.
+ *
+ * Returns: %TRUE if succeed.
  */
 gboolean             ibus_lookup_table_cursor_up(IBusLookupTable    *table);
 
 /**
  * ibus_lookup_table_cursor_down:
  * @table: An IBusLookupTable.
- * @returns: TRUE if succeed.
  *
- * Go to next candidate of an IBusLookupTable.
+ * Go to next candidate of an #IBusLookupTable.
  *
  * It returns FALSE if it is already at the last candidate,
  * unless  <code>table&gt;-round==TRUE</code>, where it will go
  * to the first candidate.
+ *
+ * Returns: %TRUE if succeed.
  */
 gboolean             ibus_lookup_table_cursor_down
                                                 (IBusLookupTable    *table);
diff --git a/src/ibusobject.h b/src/ibusobject.h
index cfc27b1f..a8b21a8a 100644
--- a/src/ibusobject.h
+++ b/src/ibusobject.h
@@ -58,6 +58,15 @@
 #define IBUS_OBJECT_GET_CLASS(obj)   \
     (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_OBJECT, IBusObjectClass))
 
+/**
+ * IBusObjectFlags:
+ * @IBUS_IN_DESTRUCTION: Used in GObjectClass::dispose
+ * @IBUS_DESTROYED: Used during emitting IBusObject::destroy signal.
+ * @IBUS_RESERVED_1: Reserved.
+ * @IBUS_RESERVED_2: Reserved.
+ *
+ * The flags are used internally.
+ */
 typedef enum {
     IBUS_IN_DESTRUCTION = (1 << 0),
     IBUS_DESTROYED      = (1 << 1),
@@ -108,9 +117,10 @@ GType           ibus_object_get_type            (void);
 
 /**
  * ibus_object_new:
- * @returns: A newly allocated IBusObject
  *
- * New an IBusObject.
+ * Creates  a new #IBusObject.
+ *
+ * Returns: A newly allocated #IBusObject
  */
 IBusObject     *ibus_object_new                 (void);
 
diff --git a/src/ibusobservedpath.h b/src/ibusobservedpath.h
index 8c8d18c3..3715380b 100644
--- a/src/ibusobservedpath.h
+++ b/src/ibusobservedpath.h
@@ -95,9 +95,10 @@ GType                ibus_observed_path_get_type            (void);
  * ibus_observed_path_new_from_xml_node:
  * @node: An XML node that contain path.
  * @fill_stat: Auto-fill the path status.
- * @returns: A newly allocated IBusObservedPath.
  *
- * New an IBusObservedPath from an XML node.
+ * Creates an new #IBusObservedPath from an XML node.
+ *
+ * Returns: A newly allocated #IBusObservedPath.
  */
 IBusObservedPath    *ibus_observed_path_new_from_xml_node   (XMLNode            *node,
                                                              gboolean            fill_stat);
@@ -106,9 +107,10 @@ IBusObservedPath    *ibus_observed_path_new_from_xml_node   (XMLNode
  * ibus_observed_path_new:
  * @path: The path string.
  * @fill_stat: Auto-fill the path status.
- * @returns: A newly allocated IBusObservedPath.
  *
- * New an IBusObservedPath from an XML node.
+ * Creates a new #IBusObservedPath from an XML node.
+ *
+ * Returns: A newly allocated #IBusObservedPath.
  */
 IBusObservedPath    *ibus_observed_path_new                 (const gchar        *path,
                                                              gboolean            fill_stat);
@@ -117,12 +119,13 @@ IBusObservedPath    *ibus_observed_path_new                 (const gchar
  * ibus_observed_path_traverse:
  * @path: An IBusObservedPath.
  * @dir_only: Only looks for subdirs, not files
- * @returns: (transfer full) (element-type IBusObservedPath): A newly allocate
- * GList which holds content in path; NULL if @path is not directory.
  *
  * Recursively traverse the path and put the files and subdirectory in to
  * a newly allocated
  * GLists, if the @path is a directory. Otherwise returns NULL.
+ *
+ * Returns: (transfer full) (element-type IBusObservedPath): A newly allocate
+ * GList which holds content in path; NULL if @path is not directory.
  */
 GList               *ibus_observed_path_traverse            (IBusObservedPath   *path,
                                                              gboolean            dir_only);
@@ -130,10 +133,11 @@ GList               *ibus_observed_path_traverse            (IBusObservedPath
 /**
  * ibus_observed_path_check_modification:
  * @path: An IBusObservedPath.
- * @returns: TRUE if mtime is changed; FALSE otherwise.
  *
- * Checks whether the path is modified by comparing the mtime in object and mtime in file system.
- * Returns TRUE if imtime is changed, otherwise FALSE.
+ * Checks whether the path is modified by comparing the mtime in object and
+ * mtime in file system.
+ *
+ * Returns: %TRUE if imtime is changed, otherwise %FALSE.
  */
 gboolean             ibus_observed_path_check_modification  (IBusObservedPath   *path);
 
diff --git a/src/ibuspanelservice.c b/src/ibuspanelservice.c
index 3a804032..27b76558 100644
--- a/src/ibuspanelservice.c
+++ b/src/ibuspanelservice.c
@@ -281,8 +281,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * @cursor_pos: The cursor position of the text.
      * @visible: Whether the update is visible.
      *
-     * Emitted when the client application get the update-preedit-text.
-     * Implement the member function update_preedit_text() in extended class
+     * Emitted when the client application get the ::update-preedit-text.
+     * Implement the member function
+     * IBusPanelServiceClass::update_preedit_text in extended class
      * to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -307,8 +308,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * @text: A preedit text to be updated.
      * @visible: Whether the update is visible.
      *
-     * Emitted when the client application get the update-auxiliary-text.
-     * Implement the member function update_auxiliary_text() in extended class
+     * Emitted when the client application get the ::update-auxiliary-text.
+     * Implement the member function
+     * IBusPanelServiceClass::update_auxiliary_text in extended class
      * to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -332,8 +334,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * @lookup_table: A lookup table to be updated.
      * @visible: Whether the update is visible.
      *
-     * Emitted when the client application get the update-lookup-table.
-     * Implement the member function update_lookup_table() in extended class
+     * Emitted when the client application get the ::update-lookup-table.
+     * Implement the member function
+     * IBusPanelServiceClass::update_lookup_table in extended class
      * to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -356,8 +359,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * @panel: An #IBusPanelService
      * @input_context_path: Object path of InputContext.
      *
-     * Emitted when the client application get the focus-in.
-     * Implement the member function focus_in() in extended class to receive
+     * Emitted when the client application get the ::focus-in.
+     * Implement the member function
+     * IBusPanelServiceClass::focus_in in extended class to receive
      * this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -379,8 +383,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * @panel: An #IBusPanelService
      * @input_context_path: Object path of InputContext.
      *
-     * Emitted when the client application get the focus-out.
-     * Implement the member function focus_out() in extended class to receive
+     * Emitted when the client application get the ::focus-out.
+     * Implement the member function
+     * IBusPanelServiceClass::focus_out in extended class to receive
      * this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -402,8 +407,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * @panel: An #IBusPanelService
      * @prop_list: An IBusPropList that contains properties.
      *
-     * Emitted when the client application get the register-properties.
-     * Implement the member function register_properties() in extended class
+     * Emitted when the client application get the ::register-properties.
+     * Implement the member function
+     * IBusPanelServiceClass::register_properties in extended class
      * to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -425,8 +431,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * @panel: An #IBusPanelService
      * @prop: The IBusProperty to be updated.
      *
-     * Emitted when the client application get the update-property.
-     * Implement the member function update_property() in extended class to
+     * Emitted when the client application get the ::update-property.
+     * Implement the member function
+     * IBusPanelServiceClass::update_property in extended class to
      * receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -451,8 +458,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * @w: Width of the cursor.
      * @h: Height of the cursor.
      *
-     * Emitted when the client application get the set-cursor-location.
-     * Implement the member function set_cursor_location() in extended class
+     * Emitted when the client application get the ::set-cursor-location.
+     * Implement the member function
+     * IBusPanelServiceClass::set_cursor_location in extended class
      * to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -476,8 +484,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * IBusPanelService::cursor-up-lookup-table:
      * @panel: An #IBusPanelService
      *
-     * Emitted when the client application get the cursor-up-lookup-table.
-     * Implement the member function cursor_up_lookup_table() in extended
+     * Emitted when the client application get the ::cursor-up-lookup-table.
+     * Implement the member function
+     * IBusPanelServiceClass::cursor_up_lookup_table in extended
      * class to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -496,8 +505,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * IBusPanelService::cursor-down-lookup-table:
      * @panel: An #IBusPanelService
      *
-     * Emitted when the client application get the cursor-down-lookup-table.
-     * Implement the member function cursor_down_lookup_table() in extended
+     * Emitted when the client application get the ::cursor-down-lookup-table.
+     * Implement the member function
+     * IBusPanelServiceClass::cursor_down_lookup_table in extended
      * class to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -516,8 +526,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * IBusPanelService::hide-auxiliary-text:
      * @panel: An #IBusPanelService
      *
-     * Emitted when the client application get the hide-auxiliary-text.
-     * Implement the member function hide_auxiliary_text() in extended class
+     * Emitted when the client application get the ::hide-auxiliary-text.
+     * Implement the member function
+     * IBusPanelServiceClass::hide_auxiliary_text in extended class
      * to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -536,8 +547,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * IBusPanelService::hide-language-bar:
      * @panel: An #IBusPanelService
      *
-     * Emitted when the client application get the hide-language-bar.
-     * Implement the member function hide_language_bar() in extended class to
+     * Emitted when the client application get the ::hide-language-bar.
+     * Implement the member function
+     * IBusPanelServiceClass::hide_language_bar in extended class to
      * receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -556,8 +568,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * IBusPanelService::hide-lookup-table:
      * @panel: An #IBusPanelService
      *
-     * Emitted when the client application get the hide-lookup-table.
-     * Implement the member function hide_lookup_table() in extended class to
+     * Emitted when the client application get the ::hide-lookup-table.
+     * Implement the member function
+     * IBusPanelServiceClass::hide_lookup_table in extended class to
      * receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -576,8 +589,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * IBusPanelService::hide-preedit-text:
      * @panel: An #IBusPanelService
      *
-     * Emitted when the client application get the hide-preedit-text.
-     * Implement the member function hide_preedit_text() in extended class to
+     * Emitted when the client application get the ::hide-preedit-text.
+     * Implement the member function
+     * IBusPanelServiceClass::hide_preedit_text in extended class to
      * receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -596,8 +610,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * IBusPanelService::page-up-lookup-table:
      * @panel: An #IBusPanelService
      *
-     * Emitted when the client application get the page-up-lookup-table.
-     * Implement the member function page_up_lookup_table() in extended class
+     * Emitted when the client application get the ::page-up-lookup-table.
+     * Implement the member function 
+     * IBusPanelServiceClass::page_up_lookup_table in extended class
      * to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -616,8 +631,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * IBusPanelService::page-down-lookup-table:
      * @panel: An #IBusPanelService
      *
-     * Emitted when the client application get the page-down-lookup-table.
-     * Implement the member function page_down_lookup_table() in extended
+     * Emitted when the client application get the ::page-down-lookup-table.
+     * Implement the member function
+     * IBusPanelServiceClass::page_down_lookup_table in extended
      * class to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -636,8 +652,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * IBusPanelService::reset:
      * @panel: An #IBusPanelService
      *
-     * Emitted when the client application get the reset.
-     * Implement the member function reset() in extended class to receive this
+     * Emitted when the client application get the ::reset.
+     * Implement the member function
+     * IBusPanelServiceClass::reset in extended class to receive this
      * signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -656,8 +673,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * IBusPanelService::show-auxiliary-text:
      * @panel: An #IBusPanelService
      *
-     * Emitted when the client application get the show-auxiliary-text.
-     * Implement the member function show_auxiliary_text() in extended class
+     * Emitted when the client application get the ::show-auxiliary-text.
+     * Implement the member function
+     * IBusPanelServiceClass::show_auxiliary_text in extended class
      * to receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -676,8 +694,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * IBusPanelService::show-language-bar:
      * @panel: An #IBusPanelService
      *
-     * Emitted when the client application get the show-language-bar.
-     * Implement the member function show_language_bar() in extended class to
+     * Emitted when the client application get the ::show-language-bar.
+     * Implement the member function
+     * IBusPanelServiceClass::show_language_bar in extended class to
      * receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -696,8 +715,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * IBusPanelService::show-lookup-table:
      * @panel: An #IBusPanelService
      *
-     * Emitted when the client application get the show-lookup-table.
-     * Implement the member function show_lookup_table() in extended class to
+     * Emitted when the client application get the ::show-lookup-table.
+     * Implement the member function
+     * IBusPanelServiceClass::show_lookup_table in extended class to
      * receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -716,8 +736,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * IBusPanelService::show-preedit-text:
      * @panel: An #IBusPanelService
      *
-     * Emitted when the client application get the show-preedit-text.
-     * Implement the member function show_preedit_text() in extended class to
+     * Emitted when the client application get the ::show-preedit-text.
+     * Implement the member function
+     * IBusPanelServiceClass::show_preedit_text in extended class to
      * receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -736,8 +757,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * IBusPanelService::start-setup:
      * @panel: An #IBusPanelService
      *
-     * Emitted when the client application get the start-setup.
-     * Implement the member function start_setup() in extended class to
+     * Emitted when the client application get the ::start-setup.
+     * Implement the member function
+     * IBusPanelServiceClass::start_setup in extended class to
      * receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -756,8 +778,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * IBusPanelService::state-changed:
      * @panel: An #IBusPanelService
      *
-     * Emitted when the client application get the state-changed.
-     * Implement the member function state_changed() in extended class to
+     * Emitted when the client application get the ::state-changed.
+     * Implement the member function
+     * IBusPanelServiceClass::state_changed in extended class to
      * receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -778,7 +801,8 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * @input_context_path: Object path of InputContext.
      *
      * Emitted when the client application destroys.
-     * Implement the member function destroy_context() in extended class to
+     * Implement the member function
+     * IBusPanelServiceClass::destroy_context in extended class to
      * receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
@@ -801,8 +825,9 @@ ibus_panel_service_class_init (IBusPanelServiceClass *class)
      * @purpose: Input purpose.
      * @hints: Input hints.
      *
-     * Emitted when the client application get the set-content-type.
-     * Implement the member function set_content_type() in extended class to
+     * Emitted when the client application get the ::set-content-type.
+     * Implement the member function
+     * IBusPanelServiceClass::set_content_type in extended class to
      * receive this signal.
      *
      * <note><para>Argument @user_data is ignored in this function.</para>
diff --git a/src/ibuspanelservice.h b/src/ibuspanelservice.h
index 0399a2f3..c3f1833c 100644
--- a/src/ibuspanelservice.h
+++ b/src/ibuspanelservice.h
@@ -132,9 +132,10 @@ GType            ibus_panel_service_get_type  (void);
 /**
  * ibus_panel_service_new:
  * @connection: An GDBusConnection.
- * @returns: A newly allocated IBusPanelService.
  *
- * New an IBusPanelService from an GDBusConnection.
+ * Creates a new #IBusPanelService from an #GDBusConnection.
+ *
+ * Returns: A newly allocated #IBusPanelService.
  */
 IBusPanelService *ibus_panel_service_new (GDBusConnection    *connection);
 
diff --git a/src/ibusproperty.h b/src/ibusproperty.h
index 0dee8804..45bab108 100644
--- a/src/ibusproperty.h
+++ b/src/ibusproperty.h
@@ -124,18 +124,6 @@ typedef struct _IBusPropListClass IBusPropListClass;
 
 /**
  * IBusProperty:
- * key: Unique Identity for the IBusProperty.
- * icon: Icon file for the IBusProperty.
- * label: Text shown in UI.
- * symbol: A symbol char showned on a button or status icon for IBusProperty.
- * 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 {
@@ -163,9 +151,10 @@ GType            ibus_property_get_type     ();
  * @visible: Whether the #IBusProperty is visible.
  * @state: IBusPropState of #IBusProperty.
  * @prop_list: (allow-none): #IBusPropList that contains sub IBusProperties.
- * @returns: A newly allocated #IBusProperty.
  *
- * New a #IBusProperty.
+ * Creates a new #IBusProperty.
+ *
+ * Returns: A newly allocated #IBusProperty.
  */
 IBusProperty    *ibus_property_new          (const gchar    *key,
                                              IBusPropType    type,
@@ -180,12 +169,14 @@ IBusProperty    *ibus_property_new          (const gchar    *key,
 /**
  * ibus_property_new_varargs:
  * @first_property_name: Name of the first property.
- * @Varargs: the NULL-terminated arguments of the properties and values.
+ * @...: the NULL-terminated arguments of the properties and values.
  *
- * New a #IBusProperty.
+ * Creates a new #IBusProperty.
  * ibus_property_new_varargs() supports the va_list format.
  * name property is required. e.g.
  * ibus_property_new_varargs("key", "TypingMode", "type", PROP_TYPE_MENU, NULL)
+ *
+ * Returns: A newly allocated #IBusProperty.
  */
 IBusProperty    *ibus_property_new_varargs  (const gchar    *first_property_name,
                                                              ...);
@@ -193,18 +184,20 @@ IBusProperty    *ibus_property_new_varargs  (const gchar    *first_property_name
 /**
  * ibus_property_get_key:
  * @prop: An #IBusProperty.
- * @returns: the key of #IBusProperty. Should not be freed.
  *
  * Get the key of #IBusProperty.
+ *
+ * Returns: the key of #IBusProperty. Should not be freed.
  */
 const gchar *    ibus_property_get_key      (IBusProperty   *prop);
 
 /**
  * ibus_property_get_label:
  * @prop: An #IBusProperty.
- * @returns: (transfer none): the label of #IBusProperty. Should not be freed.
  *
  * Get the label of #IBusProperty.
+ *
+ * Returns: (transfer none): the label of #IBusProperty. Should not be freed.
  */
 IBusText *       ibus_property_get_label    (IBusProperty   *prop);
 
@@ -221,9 +214,10 @@ void             ibus_property_set_label    (IBusProperty   *prop,
 /**
  * ibus_property_get_symbol:
  * @prop: An #IBusProperty.
- * @returns: (transfer none): the symbol of #IBusProperty. Should not be freed.
  *
  * Get the symbol of #IBusProperty.
+ *
+ * Returns: (transfer none): the symbol of #IBusProperty. Should not be freed.
  */
 IBusText *       ibus_property_get_symbol   (IBusProperty   *prop);
 
@@ -240,9 +234,10 @@ void             ibus_property_set_symbol   (IBusProperty   *prop,
 /**
  * ibus_property_get_icon:
  * @prop: An #IBusProperty.
- * @returns: the icon of #IBusProperty. Should not be freed.
  *
  * Get the icon of #IBusProperty.
+ *
+ * Returns: the icon of #IBusProperty. Should not be freed.
  */
 const gchar *    ibus_property_get_icon     (IBusProperty   *prop);
 
@@ -259,9 +254,10 @@ void             ibus_property_set_icon     (IBusProperty   *prop,
 /**
  * ibus_property_get_tooltip:
  * @prop: An #IBusProperty.
- * @returns: (transfer none): the tooltip of #IBusProperty. Should not be freed.
  *
  * Get the tooltip of #IBusProperty.
+ *
+ * Returns: (transfer none): the tooltip of #IBusProperty. Should not be freed.
  */
 IBusText *       ibus_property_get_tooltip  (IBusProperty   *prop);
 
@@ -278,9 +274,10 @@ void             ibus_property_set_tooltip  (IBusProperty   *prop,
 /**
  * ibus_property_get_sensitive:
  * @prop: An #IBusProperty.
- * @returns: the sensitive of #IBusProperty.
  *
  * Get the sensitive of #IBusProperty.
+ *
+ * Returns: the sensitive of #IBusProperty.
  */
 gboolean         ibus_property_get_sensitive(IBusProperty   *prop);
 
@@ -297,9 +294,10 @@ void             ibus_property_set_sensitive(IBusProperty   *prop,
 /**
  * ibus_property_get_visible:
  * @prop: An #IBusProperty.
- * @returns: the visible of #IBusProperty.
  *
  * Get the visible of #IBusProperty.
+ *
+ * Returns: the visible of #IBusProperty.
  */
 gboolean         ibus_property_get_visible  (IBusProperty   *prop);
 
@@ -316,18 +314,20 @@ void             ibus_property_set_visible  (IBusProperty   *prop,
 /**
  * ibus_property_get_property_type:
  * @prop: An #IBusProperty.
- * @returns: the type of #IBusProperty.
  *
  * Get the type of #IBusProperty.
+ *
+ * Returns: the type of #IBusProperty.
  */
 IBusPropType     ibus_property_get_prop_type(IBusProperty   *prop);
 
 /**
  * ibus_property_get_state:
  * @prop: An #IBusProperty.
- * @returns: the state of #IBusProperty.
  *
  * Get the state of #IBusProperty.
+ *
+ * Returns: the state of #IBusProperty.
  */
 IBusPropState    ibus_property_get_state    (IBusProperty   *prop);
 
@@ -344,10 +344,11 @@ void             ibus_property_set_state    (IBusProperty   *prop,
 /**
  * ibus_property_get_sub_props:
  * @prop: An #IBusProperty.
- * @returns: (transfer none): the IBusPropList of #IBusProperty.
- *     Should not be freed.
  *
  * Get the IBusPropList of #IBusProperty.
+ *
+ * Returns: (transfer none): the IBusPropList of #IBusProperty.
+ *     Should not be freed.
  */
 IBusPropList *   ibus_property_get_sub_props(IBusProperty   *prop);
 
@@ -365,11 +366,12 @@ void             ibus_property_set_sub_props(IBusProperty   *prop,
  * ibus_property_update:
  * @prop: An #IBusProperty.
  * @prop_update: #IBusPropList that contains sub IBusProperties.
- * @returns: TRUE for update suceeded; FALSE otherwise.
  *
  * Update the content of an #IBusProperty.
  * #IBusProperty @prop_update can either be sub-property of @prop,
  * or holds new values for @prop.
+ *
+ * Returns: TRUE for update suceeded; FALSE otherwise.
  */
 
 gboolean         ibus_property_update       (IBusProperty   *prop,
diff --git a/src/ibusproplist.h b/src/ibusproplist.h
index a8dbda23..dce60879 100644
--- a/src/ibusproplist.h
+++ b/src/ibusproplist.h
@@ -59,6 +59,19 @@ G_BEGIN_DECLS
 #define IBUS_PROP_LIST_GET_CLASS(obj)   \
     (G_TYPE_INSTANCE_GET_CLASS ((obj), IBUS_TYPE_PROP_LIST, IBusPropListClass))
 
+/* FIXME: https://mail.gnome.org/archives/gtk-doc-list/2015-July/msg00004.html
+ * If ibusproperty.h and ibusproplist.h includes each other,
+ * gtk-doc build outputs several warnings:
+ *
+ * # cd html && gtkdoc-mkhtml ibus ../ibus-docs.sgml
+ * ../ibus-docs.sgml:4: element refentry: validity error : ID IBusPropList
+ * already defined
+ * ../ibus-docs.sgml:172: element refsect2: validity error : ID
+ * IBusPropListClass already defined
+ * Warning: multiple "IDs" for constraint linkend: IBusPropList.
+ * Warning: multiple "IDs" for constraint linkend: IBusPropList.
+ * Warning: multiple "IDs" for constraint linkend: IBusPropListClass.
+ */
 #ifndef __PROPLIST_DEFINED
 #define __PROPLIST_DEFINED
 typedef struct _IBusPropList IBusPropList;
@@ -78,6 +91,12 @@ struct _IBusPropList {
     GArray *properties;
 };
 
+/**
+ * IBusPropListClass:
+ * @parent: The parent class.
+ *
+ * Class structure for #IBusPropList.
+ */
 struct _IBusPropListClass {
     IBusSerializableClass parent;
 };
@@ -86,9 +105,10 @@ GType            ibus_prop_list_get_type    ();
 
 /**
  * ibus_prop_list_new:
- * @returns: A newly allocated IBusPropList.
  *
- * New a IBusPropList.
+ * Create a new #IBusPropList.
+ *
+ * Returns: A newly allocated #IBusPropList.
  */
 IBusPropList    *ibus_prop_list_new         ();
 
@@ -106,9 +126,11 @@ void             ibus_prop_list_append      (IBusPropList   *prop_list,
  * ibus_prop_list_get:
  * @prop_list: An IBusPropList.
  * @index: Index of an IBusPropList.
- * @returns: (transfer none): IBusProperty at given index, NULL if no such IBusProperty.
  *
- * Returns IBusProperty at given index. Borrowed reference.
+ * Gets #IBusProperty at given index. Borrowed reference.
+ *
+ * Returns: (transfer none): #IBusProperty at given index, %NULL if no such
+ *     #IBusProperty.
  */
 IBusProperty    *ibus_prop_list_get         (IBusPropList   *prop_list,
                                              guint           index);
@@ -117,9 +139,10 @@ IBusProperty    *ibus_prop_list_get         (IBusPropList   *prop_list,
  * 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.
+ *
+ * Returns: %TRUE if succeeded, %FALSE otherwise.
  */
 gboolean         ibus_prop_list_update_property
                                             (IBusPropList   *prop_list,
diff --git a/src/ibusproxy.h b/src/ibusproxy.h
index a2b52f56..7365863b 100644
--- a/src/ibusproxy.h
+++ b/src/ibusproxy.h
@@ -99,12 +99,15 @@ GType   ibus_proxy_get_type (void);
 
 /**
  * ibus_proxy_destroy:
+ * @proxy: An #IBusProxy
  *
- * Dispose the proxy object. If the dbus connection is alive and the own variable above
- * is TRUE (which is the default), org.freedesktop.IBus.Service.Destroy method will be
- * called. Note that "destroy" signal might be emitted when ibus_proxy_destroy is called
- * or the underlying dbus connection for the proxy is terminated. In the callback of the
- * destroy signal, you might have to call something like 'g_object_unref(the_proxy);'.
+ * Dispose the proxy object. If the dbus connection is alive and the own
+ * variable above is TRUE (which is the default),
+ * org.freedesktop.IBus.Service.Destroy method will be called.
+ * Note that "destroy" signal might be emitted when ibus_proxy_destroy is
+ * called or the underlying dbus connection for the proxy is terminated.
+ * In the callback of the destroy signal, you might have to call something
+ * like 'g_object_unref(the_proxy);'.
  */
 void    ibus_proxy_destroy  (IBusProxy      *proxy);
 
diff --git a/src/ibusregistry.h b/src/ibusregistry.h
index 9522f1a8..6a540cc4 100644
--- a/src/ibusregistry.h
+++ b/src/ibusregistry.h
@@ -88,9 +88,10 @@ GType            ibus_registry_get_type         (void);
 
 /**
  * ibus_registry_new:
- * @returns: A newly allocated #IBusRegistry.
  *
- * New a #IBusRegistry
+ * Creates a new #IBusRegistry
+ *
+ * Returns: A newly allocated #IBusRegistry.
  */
 IBusRegistry    *ibus_registry_new              (void);
 
@@ -122,10 +123,11 @@ void             ibus_registry_load_in_dir      (IBusRegistry   *registry,
  * ibus_registry_load_cache:
  * @registry: An #IBusRegistry.
  * @is_user: %TRUE if the registry cache is loaded in the user directory.
- * @returns: %TRUE if the cache exists and is loaded successfully,
- *           %FALSE otherwise.
  *
  * Load the user or system registry cache.
+ *
+ * Returns: %TRUE if the cache exists and is loaded successfully,
+ *           %FALSE otherwise.
  */
 gboolean         ibus_registry_load_cache       (IBusRegistry   *registry,
                                                  gboolean        is_user);
@@ -134,10 +136,11 @@ gboolean         ibus_registry_load_cache       (IBusRegistry   *registry,
  * ibus_registry_load_cache_file:
  * @registry: An #IBusRegistry.
  * @filename: The file path of the registry cache
- * @returns: %TRUE if the cache exists and is loaded successfully,
- *           %FALSE otherwise.
  *
  * Load the registry cache @filename.
+ *
+ * Returns: %TRUE if the cache exists and is loaded successfully,
+ *           %FALSE otherwise.
  */
 gboolean         ibus_registry_load_cache_file  (IBusRegistry   *registry,
                                                  const gchar    *filename);
@@ -146,9 +149,10 @@ gboolean         ibus_registry_load_cache_file  (IBusRegistry   *registry,
  * ibus_registry_save_cache:
  * @registry: An #IBusRegistry.
  * @is_user: %TRUE if the registry cache is saved in the user directory.
- * @returns: %TRUE if the cache is saved successfully, %FALSE otherwise.
  *
  * Save the registry in a user directory or system directory.
+ *
+ * Returns: %TRUE if the cache is saved successfully, %FALSE otherwise.
  */
 gboolean         ibus_registry_save_cache       (IBusRegistry   *registry,
                                                  gboolean        is_user);
@@ -157,9 +161,10 @@ gboolean         ibus_registry_save_cache       (IBusRegistry   *registry,
  * ibus_registry_save_cache_file:
  * @registry: An #IBusRegistry.
  * @filename: The file path of the registry cache
- * @returns: %TRUE if the cache is saved successfully, %FALSE otherwise.
  *
  * Save the registry cache @filename.
+ *
+ * Returns: %TRUE if the cache is saved successfully, %FALSE otherwise.
  */
 gboolean         ibus_registry_save_cache_file  (IBusRegistry   *registry,
                                                  const gchar    *filename);
@@ -180,9 +185,10 @@ void             ibus_registry_output           (IBusRegistry   *registry,
 /**
  * ibus_registry_check_modification:
  * @registry: An #IBusRegistry.
- * @returns: %TRUE if mtime is changed; %FALSE otherwise.
  *
  * Check if the registry is updated.
+ *
+ * Returns: %TRUE if mtime is changed; %FALSE otherwise.
  */
 gboolean         ibus_registry_check_modification
                                                 (IBusRegistry   *registry);
@@ -190,22 +196,24 @@ gboolean         ibus_registry_check_modification
 /**
  * ibus_registry_get_components:
  * @registry: An #IBusRegistry.
- * @returns: (transfer container) (element-type IBusComponent):
- * a list of #IBusComponent objects.
- * The caller has to call g_list_free() for the returned list.
  *
  * List components.
+ *
+ * Returns: (transfer container) (element-type IBusComponent):
+ * a list of #IBusComponent objects.
+ * The caller has to call g_list_free() for the returned list.
  */
 GList           *ibus_registry_get_components   (IBusRegistry   *registry);
 
 /**
  * ibus_registry_get_observed_paths:
  * @registry: An #IBusRegistry.
- * @returns: (transfer container) (element-type IBusObservedPath):
- * a list of #IBusObservedPath objects.
- * The caller has to call g_list_free() for the returned list.
  *
  * List observed paths.
+ *
+ * Returns: (transfer container) (element-type IBusObservedPath):
+ * a list of #IBusObservedPath objects.
+ * The caller has to call g_list_free() for the returned list.
  */
 GList           *ibus_registry_get_observed_paths
                                                 (IBusRegistry   *registry);
diff --git a/src/ibusserializable.h b/src/ibusserializable.h
index d12c47be..4327eaee 100644
--- a/src/ibusserializable.h
+++ b/src/ibusserializable.h
@@ -129,12 +129,13 @@ struct _IBusSerializable {
  * IBusSerializableSerializeFunc:
  * @serializable: An #IBusSerializable.
  * @builder: A #GVariantBuilder.
- * @returns: %TRUE if succeed; %FALSE otherwise.
  *
  * Prototype of serialize function.
  * Serialize function convert an #IBusSerializable to #GVariantBuilder.
  * Returns a gboolean value which indicates whether the conversion is success.
  * Return %TRUE if succeed.
+ *
+ * Returns: %TRUE if succeed; %FALSE otherwise.
  */
 typedef gboolean    (* IBusSerializableSerializeFunc)   (IBusSerializable       *serializable,
                                                          GVariantBuilder        *builder);
@@ -143,12 +144,13 @@ typedef gboolean    (* IBusSerializableSerializeFunc)   (IBusSerializable
  * IBusSerializableDeserializeFunc:
  * @serializable: An #IBusSerializable.
  * @variant: A #GVariant contains a tuple.
- * @returns: The number of values in the variant(tuple) are consumed.
  *
  * Prototype of deserialize function.
  * Deserialize function convert a #GVariant to #IBusSerializable.
  * Returns an integer value which indicates how many values in
  * the variant(tuple) are consumed.
+ *
+ * Returns: The number of values in the variant(tuple) are consumed.
  */
 typedef gint        (* IBusSerializableDeserializeFunc) (IBusSerializable       *serializable,
                                                          GVariant               *variant);
@@ -157,11 +159,12 @@ typedef gint        (* IBusSerializableDeserializeFunc) (IBusSerializable
  * IBusSerializableCopyFunc:
  * @dest: The destination #IBusSerializable.
  * @src: A source #IBusSerializable.
- * @returns: %TRUE if succeed; %FALSE otherwise.
  *
  * Prototype of copy function.
  * Copy function copy from source #IBusSerializable to the destination one.
  * Returns a gboolean value which indicates whether the copying is success.
+ *
+ * Returns: %TRUE if succeed; %FALSE otherwise.
  */
 typedef gboolean    (* IBusSerializableCopyFunc)        (IBusSerializable       *dest,
                                                          const IBusSerializable *src);
@@ -211,9 +214,11 @@ void                 ibus_serializable_set_qattachment  (IBusSerializable   *ser
  * ibus_serializable_get_qattachment:
  * @serializable: An #IBusSerializable.
  * @key: String formatted key for indexing value.
- * @returns: The attached value; or %NULL if fail to retrieve the value.
  *
- * Get a value from attachment of an #IBusSerializable.
+ * Gets a value from attachment of an #IBusSerializable.
+ *
+ * Returns: The attached value; or %NULL if fail to retrieve the value.
+ *
  * See also: ibus_serializable_set_attachment().
  */
 GVariant            *ibus_serializable_get_qattachment  (IBusSerializable   *serializable,
@@ -234,12 +239,13 @@ void                 ibus_serializable_remove_qattachment
 /**
  * ibus_serializable_copy:
  * @serializable: An #IBusSerializable.
- * @returns: (transfer none): A newly allocated clone object; or %NULL
- *     if @object is not serializable.
  *
  * Clone an #IBusSerializable.
  * The copy method should be implemented in extended class.
  *
+ * Returns: (transfer none): A newly allocated clone object; or %NULL
+ *     if @object is not serializable.
+ *
  * See also: IBusSerializableCopyFunc().
  */
 IBusSerializable    *ibus_serializable_copy             (IBusSerializable   *serializable);
@@ -247,11 +253,12 @@ IBusSerializable    *ibus_serializable_copy             (IBusSerializable   *ser
 /**
  * ibus_serializable_serialize:
  * @serializable: An #IBusSerializable.
- * @returns: A #GVariant.
  *
  * Serialize an #IBusSerializable to a #GVariant.
  * The serialize method should be implemented in extended class.
  *
+ * Returns: A #GVariant.
+ *
  * See also: IBusSerializableCopyFunc().
  */
 GVariant            *ibus_serializable_serialize        (IBusSerializable   *serializable);
@@ -259,11 +266,12 @@ GVariant            *ibus_serializable_serialize        (IBusSerializable   *ser
 /**
  * ibus_serializable_deserialize:
  * @variant: A #GVariant.
- * @returns: (transfer none): The deserialized #IBusSerializable.
  *
  * Deserialize a #GVariant to an #IBusSerializable/
  * The deserialize method should be implemented in extended class.
  *
+ * Returns: (transfer none): The deserialized #IBusSerializable.
+ *
  * See also: IBusSerializableCopyFunc().
  */
 IBusSerializable    *ibus_serializable_deserialize      (GVariant           *variant);
diff --git a/src/ibusservice.h b/src/ibusservice.h
index 829f5735..d3723a97 100644
--- a/src/ibusservice.h
+++ b/src/ibusservice.h
@@ -112,10 +112,11 @@ struct _IBusServiceClass {
      * @interface_name: An interface name.
      * @property_name: A property name.
      * @error: Return location for error or %NULL.
-     * @returns: (nullable) (transfer full): A variant.
      *
      * The ::service_get_property class method is to connect
      * GDBusInterfaceGetPropertyFunc().
+     *
+     * Returns: (nullable) (transfer full): A variant.
      */
     GVariant *  (* service_get_property)
                                     (IBusService        *service,
@@ -135,10 +136,11 @@ struct _IBusServiceClass {
      * @property_name: An property name.
      * @value: An property value.
      * @error: Return location for error or %NULL.
-     * @returns: %TRUE if set the value else %FALSE.
      *
      * The ::service_set_property class method is to connect
      * GDBusInterfaceSetPropertyFunc().
+     *
+     * Returns: %TRUE if set the value else %FALSE.
      */
     gboolean    (* service_set_property)
                                     (IBusService        *service,
@@ -161,28 +163,32 @@ GType            ibus_service_get_type          (void);
 
 /**
  * ibus_service_new:
+ * @connection: A GDBusConnection.
  * @path: Object path.
- * @returns: A newly allocated IBusService
  *
- * New an IBusService.
+ * Creantes a new #IBusService.
+ *
+ * Returns: A newly allocated #IBusService
  */
 IBusService     *ibus_service_new               (GDBusConnection    *connection,
                                                  const gchar        *path);
 /**
  * ibus_service_get_object_path:
  * @service: An IBusService.
- * @returns: The object path of @service
  *
- * Returns the object path of an IBusService.
+ * Gets the object path of an IBusService.
+ *
+ * Returns: The object path of @service
  */
 const gchar     *ibus_service_get_object_path   (IBusService        *service);
 
 /**
  * ibus_service_get_connection:
  * @service: An IBusService.
- * @returns: (transfer none): A #GDBusConnection of an #IBusService instance.
  *
- * Returns a connections.
+ * Gets a connections.
+ *
+ * Returns: (transfer none): A #GDBusConnection of an #IBusService instance.
  */
 GDBusConnection *ibus_service_get_connection    (IBusService        *service);
 
@@ -191,9 +197,10 @@ GDBusConnection *ibus_service_get_connection    (IBusService        *service);
  * @service: An IBusService.
  * @connection: A GDBusConnection the service will be registered to.
  * @error: Return location for error or NULL.
- * @returns: TRUE if the service was registered, FALSE otherwise.
  *
  * Registers service to a connection.
+ *
+ * Returns: %TRUE if the service was registered, %FALSE otherwise.
  */
 gboolean         ibus_service_register          (IBusService        *service,
                                                  GDBusConnection    *connection,
@@ -217,9 +224,10 @@ void             ibus_service_unregister        (IBusService        *service,
  * @name: Name of the signal.
  * @first_arg_type: Type of first argument.
  * @...: Rest of arguments, NULL to mark the end.
- * @returns: TRUE if succeed; FALSE otherwise.
  *
- * Send signal to all the IBusConnections of an IBusService.
+ * Sends signal to all the #IBusConnections of an #IBusService.
+ *
+ * Returns: %TRUE if succeed; %FALSE otherwise.
  *
  * see_also: g_dbus_connection_emit_signal()
  */
@@ -235,6 +243,9 @@ gboolean         ibus_service_emit_signal       (IBusService        *service,
  * @xml_data: The introspection xml data.
  *
  * Set the interface introspection information with the service class.
+ *
+ * Returns: %TRUE if @xml_data is valid and succeeded to be added;
+ *          %FALSE otherwise.
  */
 gboolean         ibus_service_class_add_interfaces
                                                 (IBusServiceClass   *klass,
diff --git a/src/ibusshare.h b/src/ibusshare.h
index 744bab88..bca477c0 100644
--- a/src/ibusshare.h
+++ b/src/ibusshare.h
@@ -168,9 +168,10 @@ G_BEGIN_DECLS
 
 /**
  * ibus_get_local_machine_id:
- * @returns: A newly allocated string that shows the UUID of the machine.
  *
  * Obtains the machine UUID of the machine this process is running on.
+ *
+ * Returns: A newly allocated string that shows the UUID of the machine.
  */
 const gchar     *ibus_get_local_machine_id
                                         (void);
@@ -185,7 +186,6 @@ void             ibus_set_display       (const gchar    *display);
 
 /**
  * ibus_get_address:
- * @returns: D-Bus address of IBus. %NULL for not found.
  *
  * Return the D-Bus address of IBus.
  * It will find the address from following source:
@@ -194,6 +194,8 @@ void             ibus_set_display       (const gchar    *display);
  *    <listitem><para>Socket file under ~/.config/ibus/bus/</para></listitem>
  * </orderedlist>
  *
+ * Returns: D-Bus address of IBus. %NULL for not found.
+ *
  * See also: ibus_write_address().
  */
 const gchar     *ibus_get_address       (void);
@@ -210,7 +212,6 @@ void             ibus_write_address     (const gchar    *address);
 
 /**
  * ibus_get_user_name:
- * @returns: A newly allocated string that stores current user name.
  *
  * Get the current user name.
  * It is determined by:
@@ -223,15 +224,18 @@ void             ibus_write_address     (const gchar    *address);
  *    <listitem><para>Environment variable USER</para></listitem>
  *    <listitem><para>Environment variable LNAME</para></listitem>
  * </orderedlist>
+ *
+ * Returns: A newly allocated string that stores current user name.
  */
 const gchar     *ibus_get_user_name     (void);
 
 /**
  * ibus_get_daemon_uid:
- * @returns: UID of ibus-daemon; or 0 if UID is not available.
  *
  * Get UID of ibus-daemon.
  *
+ * Returns: UID of ibus-daemon; or 0 if UID is not available.
+ *
  * Deprecated: This function has been deprecated and should
  * not be used in newly written code.
  */
@@ -239,18 +243,23 @@ glong            ibus_get_daemon_uid    (void) G_GNUC_DEPRECATED;
 
 /**
  * ibus_get_socket_path:
- * @returns: A newly allocated string that stores the path of socket file.
  *
  * Get the path of socket file.
+ *
+ * Returns: A newly allocated string that stores the path of socket file.
  */
 const gchar     *ibus_get_socket_path   (void);
 
 /**
  * ibus_get_timeout:
- * @returns: A GDBus timeout in milliseconds. -1 when default timeout for GDBus should be used.
  *
- * Get the GDBus timeout in milliseconds. The timeout is for clients (e.g. im-ibus.so), not for ibus-daemon.
- * Note that the timeout for ibus-daemon could be set by --timeout command line option of the daemon.
+ * Get the GDBus timeout in milliseconds. The timeout is for clients (e.g.
+ * im-ibus.so), not for ibus-daemon.
+ * Note that the timeout for ibus-daemon could be set by --timeout command
+ * line option of the daemon.
+ *
+ * Returns: A GDBus timeout in milliseconds. -1 when default timeout for
+ *     GDBus should be used.
  */
 gint             ibus_get_timeout       (void);
 
@@ -269,12 +278,13 @@ void             ibus_free_strv         (gchar          **strv)
  * ibus_key_event_to_string:
  * @keyval: Key symbol.
  * @modifiers: Modifiers such as Ctrl or Shift.
- * @returns: The name of a key symbol and modifier.
  *
  * Return the name of a key symbol and modifiers.
  *
  * For example, if press ctrl, shift, and enter, then this function returns:
  * Shift+Control+enter.
+ *
+ * Returns: The name of a key symbol and modifier.
  */
 const gchar     *ibus_key_event_to_string
                                         (guint           keyval,
@@ -285,9 +295,10 @@ const gchar     *ibus_key_event_to_string
  * @string: Key event string.
  * @keyval: Variable that hold key symbol result.
  * @modifiers: Variable that hold modifiers result.
- * @returns: TRUE for succeed; FALSE if failed.
  *
  * Parse key event string and return key symbol and modifiers.
+ *
+ * Returns: %TRUE for succeed; %FALSE if failed.
  */
 gboolean         ibus_key_event_from_string
                                         (const gchar    *string,
diff --git a/src/ibustext.h b/src/ibustext.h
index 02116072..e5e3c4a9 100644
--- a/src/ibustext.h
+++ b/src/ibustext.h
@@ -91,34 +91,37 @@ 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 from a string.
+ * Creates a new #IBusText from a string.
+ * @str will be duplicated in #IBusText, so feel free to free @str after this
+ * function.
  *
- * @str will be duplicated in IBusText, so feel free to free @str after this function.
+ * Returns: A newly allocated #IBusText.
  */
 IBusText        *ibus_text_new_from_string          (const gchar    *str);
 
 /**
  * ibus_text_new_from_ucs4:
  * @str: An text string to be set.
- * @returns: A newly allocated IBusText.
  *
- * New an IBusText from an UCS-4 encoded string.
+ * Creates a new #IBusText from an UCS-4 encoded string.
+ * @str will be duplicated in IBusText, so feel free to free @str after this
+ * function.
  *
- * @str will be duplicated in IBusText, so feel free to free @str after this function.
+ * Returns: A newly allocated #IBusText.
  */
 IBusText        *ibus_text_new_from_ucs4            (const gunichar *str);
 
 /**
  * ibus_text_new_from_static_string: (skip)
  * @str: An text string to be set.
- * @returns: A newly allocated IBusText.
  *
- * New an IBusText from a static string.
+ * Creates a new #IBusText from a static string.
  *
  * Since @str is a static string which won't be freed.
  * This function will NOT duplicate @str.
+ *
+ * Returns: A newly allocated #IBusText.
  */
 IBusText        *ibus_text_new_from_static_string   (const gchar    *str);
 
@@ -126,11 +129,12 @@ IBusText        *ibus_text_new_from_static_string   (const gchar    *str);
  * ibus_text_new_from_printf:
  * @fmt: printf format string.
  * @...: arguments for @fmt.
- * @returns: A newly allocated IBusText.
  *
- * New an IBusText from a printf expression.
+ * Creates a new #IBusText from a printf expression.
  *
  * The result of printf expression is stored in the new IBusText instance.
+ *
+ * Returns: A newly allocated #IBusText.
  */
 IBusText        *ibus_text_new_from_printf          (const gchar    *fmt,
                                                      ...) G_GNUC_PRINTF (1, 2);
@@ -138,9 +142,10 @@ 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.
+ * Creates a new #IBusText from a single UCS4-encoded character.
+ *
+ * Returns: A newly allocated #IBusText.
  */
 IBusText        *ibus_text_new_from_unichar         (gunichar        c);
 
@@ -161,39 +166,43 @@ void             ibus_text_append_attribute         (IBusText       *text,
                                                      gint            end_index);
 /**
  * ibus_text_get_length:
- * @text: An IBusText.
- * @returns: Number of character in @text, not counted by bytes.
+ * @text: An #IBusText.
  *
- * Return number of characters in an IBusText.
+ * 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.
+ *
+ * Returns: Number of character in @text, not counted by bytes.
  */
 guint            ibus_text_get_length               (IBusText       *text);
 
 /**
  * ibus_text_get_is_static: (skip)
- * @text: An IBusText.
- * @returns: the is_static in @text.
+ * @text: An #IBusText.
  *
- * Return the is_static in an IBusText.
+ * Return the is_static in an #IBusText.
+ *
+ * Returns: the is_static in @text.
  */
 gboolean         ibus_text_get_is_static            (IBusText       *text);
 
 /**
  * ibus_text_get_text:
- * @text: An IBusText.
- * @returns: the text in @text.
+ * @text: An #IBusText.
+ *
+ * Return the text in an #IBusText. Should not be freed.
  *
- * Return the text in an IBusText. Should not be freed.
+ * Returns: the text in @text.
  */
 const gchar *    ibus_text_get_text                 (IBusText       *text);
 
 /**
  * ibus_text_get_attributes:
- * @text: An IBusText.
- * @returns: (transfer none): the attrs in @text.
+ * @text: An #IBusText.
+ *
+ * Return the attributes in an #IBusText. Should not be freed.
  *
- * Return the attributes in an IBusText. Should not be freed.
+ * Returns: (transfer none): the attrs in @text.
  */
 IBusAttrList *   ibus_text_get_attributes           (IBusText       *text);
 
diff --git a/src/ibusutil.h b/src/ibusutil.h
index b9b6415e..2c1360c7 100644
--- a/src/ibusutil.h
+++ b/src/ibusutil.h
@@ -39,7 +39,8 @@
 /**
  * ibus_get_untranslated_language_name:
  * @_locale: A const locale name.
- * @returns: untranslated language name
+ *
+ * Returns: untranslated language name
  */
 const gchar *    ibus_get_untranslated_language_name
                                                 (const gchar    *_locale);
@@ -47,7 +48,8 @@ const gchar *    ibus_get_untranslated_language_name
 /**
  * ibus_get_language_name:
  * @_locale: A const locale name.
- * @returns: translated language name
+ *
+ * Returns: translated language name
  */
 const gchar *    ibus_get_language_name         (const gchar    *_locale);
 
diff --git a/src/ibusxml.h b/src/ibusxml.h
index 826c9abe..1bbc6fcd 100644
--- a/src/ibusxml.h
+++ b/src/ibusxml.h
@@ -56,19 +56,21 @@ typedef struct {
 /**
  * ibus_xml_parse_file:
  * @name: File name to be parsed.
- * @returns: Root node of parsed XML tree.
  *
  * Parse an XML file and return a corresponding XML tree.
+ *
+ * Returns: Root node of parsed XML tree.
  */
 XMLNode *ibus_xml_parse_file    (const gchar    *name);
 
 /**
  * ibus_xml_parse_buffer:
  * @buffer: Buffer to be parsed.
- * @returns: Root node of parsed XML tree.
  *
  * Parse a string buffer which contains an XML-formatted string,
  * and return a corresponding XML tree.
+ *
+ * Returns: Root node of parsed XML tree.
  */
 XMLNode *ibus_xml_parse_buffer  (const gchar    *buffer);