From: dchen@redhat.com Date: Fri, 17 Apr 2009 06:10:21 +0000 (+1000) Subject: API DOC-new: ibusdebug IBusError IBusFactory; and revised. X-Git-Tag: 1.1.0.20090417~6^2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=912f742d1224bd02167c3da707a3167767e22bc4;p=platform%2Fupstream%2Fibus.git API DOC-new: ibusdebug IBusError IBusFactory; and revised. --- diff --git a/docs/reference/ibus/Makefile.am b/docs/reference/ibus/Makefile.am index 3682251..db6aac1 100644 --- a/docs/reference/ibus/Makefile.am +++ b/docs/reference/ibus/Makefile.am @@ -98,17 +98,19 @@ EXTRA_DIST += # Comment this out if you want your docs-status tested during 'make check' #TESTS = $(GTKDOC_CHECK) -trim-sections.txt: +trim-sections.txt: $(DOC_MODULE)-sections.txt cp $(DOC_MODULE)-sections.txt $(DOC_MODULE)-sections.txt.old sed '/IBusAttrList<\/TITLE>/d' $(DOC_MODULE)-sections.txt.old > $(DOC_MODULE)-sections.txt cp $(DOC_MODULE)-sections.txt $(DOC_MODULE)-sections.txt.old sed '/<TITLE>IBusPropList<\/TITLE>/d' $(DOC_MODULE)-sections.txt.old > $(DOC_MODULE)-sections.txt + cp $(DOC_MODULE)-sections.txt $(DOC_MODULE)-sections.txt.old + sed '/<TITLE>IBusFactoryInfo<\/TITLE>/d' $(DOC_MODULE)-sections.txt.old > $(DOC_MODULE)-sections.txt tmpl-build.stamp: trim-sections.txt $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-overrides.txt clean-local: - rm -rf tmpl + rm -rf tmpl ${DOC_MODULE) -CLEANFILES+= *.stamp +CLEANFILES+= *.stamp $(DOC_MODULE)-sections.txt diff --git a/src/ibusbus.c b/src/ibusbus.c index cfc7e39..57a5453 100644 --- a/src/ibusbus.c +++ b/src/ibusbus.c @@ -107,7 +107,7 @@ ibus_bus_class_init (IBusBusClass *klass) /** * IBusBus::connected: * - * The IBusBus is connected. + * Emitted when IBusBus is connected. */ bus_signals[CONNECTED] = g_signal_new (I_("connected"), @@ -122,7 +122,7 @@ ibus_bus_class_init (IBusBusClass *klass) /** * IBusBus::disconnected: * - * The IBusBus is disconnected. + * Emitted when IBusBus is disconnected. */ bus_signals[DISCONNECTED] = g_signal_new (I_("disconnected"), diff --git a/src/ibusconfigservice.h b/src/ibusconfigservice.h index 7333bb7..48e7665 100644 --- a/src/ibusconfigservice.h +++ b/src/ibusconfigservice.h @@ -168,7 +168,7 @@ GType ibus_config_service_get_type (void); IBusConfigService *ibus_config_service_new (IBusConnection *connection); /** - * ibus_config_service_value_change: + * ibus_config_service_value_changed: * @config: An IBusConfigService. * @section: Section name of the configuration option. * @name: Name of the configure option. diff --git a/src/ibusconnection.c b/src/ibusconnection.c index 4a135dd..1ba12ad 100644 --- a/src/ibusconnection.c +++ b/src/ibusconnection.c @@ -113,13 +113,16 @@ ibus_connection_class_init (IBusConnectionClass *klass) /* install signals */ /** - * IBusConnnection::ibus-message: + * IBusConnection::ibus-message: * @ibusconnection: The object which received the signal. * @message: An IBusMessage. - * @returns: TRUE if succeed; FALSE otherwise. * - * Emitted ::ibus-message when sending an ibus-message. - * Implement this function in extended class to receive this signal. + * Emitted when sending an ibus-message. + * Implement the member function ibus_message() in extended class to receive this signal. + * + * <note><para>@user_data is not actually a valid parameter. It is displayed because GtkDoc.</para></note> + * + * Returns: TRUE if succeed; FALSE otherwise. */ connection_signals[IBUS_MESSAGE] = g_signal_new (I_("ibus-message"), @@ -132,13 +135,16 @@ ibus_connection_class_init (IBusConnectionClass *klass) G_TYPE_POINTER); /** - * IBusConnnection::ibus-signal: + * IBusConnection::ibus-signal: * @ibusconnection: The object which received the signal. * @message: An IBusMessage that contain the signal. - * @returns: TRUE if succeed; FALSE otherwise. * - * Emitted ::ibus-signal when sending an ibus-signal. - * Implement this function in extended class to receive this signal. + * Emitted when sending an ibus-signal. + * Implement the member function ibus_signal() function in extended class to receive this signal. + * + * <note><para>@user_data is not actually a valid parameter. It is displayed because GtkDoc.</para></note> + * + * Returns: TRUE if succeed; FALSE otherwise. */ connection_signals[IBUS_SIGNAL] = g_signal_new (I_("ibus-signal"), @@ -151,12 +157,14 @@ ibus_connection_class_init (IBusConnectionClass *klass) G_TYPE_POINTER); /** - * IBusConnnection::ibus-message-sent: + * IBusConnection::ibus-message-sent: * @ibusconnection: The object which received the signal. * @message: An IBusMessage that contain the signal. * - * Emitted ::ibus-message-sent when an ibus-message is sent. - * Implement this function in extended class to receive this signal. + * Emitted when an ibus-message is sent. + * Implement the member function ibus_message_sent() function in extended class to receive this signal. + * + * <note><para>@user_data is not actually a valid parameter. It is displayed because GtkDoc.</para></note> */ connection_signals[IBUS_MESSAGE_SENT] = g_signal_new (I_("ibus-message-sent"), @@ -169,11 +177,14 @@ ibus_connection_class_init (IBusConnectionClass *klass) G_TYPE_POINTER); /** - * IBusConnnection::disconnect: + * IBusConnection::disconnected: * @ibusconnection: The object which received the signal. * - * Emitted ::disconnect when an ibus-message is disconnected. - * Implement this function in extended class to receive this signal. + * Emitted when an ibus-message is disconnected. + * Implement the member function disconnected() function in extended class to receive this signal. + * + * <note><para>@user_data is not actually a valid parameter. It is displayed because GtkDoc.</para></note> + * */ connection_signals[DISCONNECTED] = g_signal_new (I_("disconnected"), diff --git a/src/ibusconnection.h b/src/ibusconnection.h index b4a5539..e18bfe3 100644 --- a/src/ibusconnection.h +++ b/src/ibusconnection.h @@ -20,12 +20,13 @@ /** * SECTION: ibusconnection * @short_description: DBusConnection wrapper. + * @stability: Stable * @see_also: IBusMessage * <ulink url="http://dbus.freedesktop.org/doc/api/html/structDBusConnection.html">DBusConnection</ulink> * - * An IBusConnection provides DBusConnection wrapper, and is used to connect to either D-Bus or IBus daemon. - * Usually, IBusConnection is set to a DBusConnection and emitting ibus-message when - * receiving incoming messages from the DBusConnection. + * An IBusConnection provides #DBusConnection wrapper, and is used to connect to either D-Bus or IBus daemon. + * Usually, IBusConnection is set to a #DBusConnection and emitting ibus-message when + * receiving incoming messages from the #DBusConnection. */ #ifndef __IBUS_CONNECTION_H_ @@ -396,9 +397,6 @@ IBusMessage *ibus_connection_send_with_reply_and_block * @interface: The interface the signal is emitted from. * @member: The name of the member function to be called. * @error: Error is stored here; NULL to ignore error. - * @message: An IBusMessage. - * @timeout_milliseconds: timeout in milliseconds or -1 for default. - * @error: Error is stored here; NULL to ignore error. * @first_arg_type: Type of first arg. * @returns: TRUE if succeed; FALSE otherwise. * @@ -416,7 +414,7 @@ gboolean ibus_connection_call (IBusConnection *connect ...); /** - * ibus_connection_call: + * ibus_connection_flush: * @connection: An IBusConnection. * * Blocks until the outgoing message queue is empty. diff --git a/src/ibusdebug.h b/src/ibusdebug.h index 7a59a8d..9cf6826 100644 --- a/src/ibusdebug.h +++ b/src/ibusdebug.h @@ -17,9 +17,27 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION: ibusdebug + * @short_description: Debug message output. + * @stability: Stable + * + * This section lists functions that generate debug and warning messages. + */ #ifndef __IBUS_DEBUG_H_ #define __IBUS_DEBUG_H_ +/** + * ibus_warning: + * @msg: A printf formatted message to be print. + * @args...: Necessary arguments for @msg. + * + * A convenient wrapper for g_warning. + * The output format will be + * <programlisting> + * source_file:line, message... + * </programlisting> + */ #define ibus_warning(msg, args...) \ g_warning("%s:%d, " msg, __FILE__, __LINE__, ##args) diff --git a/src/ibusengine.c b/src/ibusengine.c index b7421ad..e5bcb59 100644 --- a/src/ibusengine.c +++ b/src/ibusengine.c @@ -224,7 +224,9 @@ ibus_engine_class_init (IBusEngineClass *klass) * @state: Key modifier flags * * Emitted when a key event is received. - * Implement this function in extended class to receive this signal. + * Implement the member function process_key_event() in extended class to receive this signal. + * + * <note><para>@user_data is not actually a valid parameter. It is displayed because GtkDoc.</para></note> */ engine_signals[PROCESS_KEY_EVENT] = g_signal_new (I_("process-key-event"), @@ -242,8 +244,10 @@ ibus_engine_class_init (IBusEngineClass *klass) * IBusEngine::focus-in: * @engine: An IBusEngine. * - * Emitted when the client application get the focus. - * Implement this function in extended class to receive this signal. + * Emitted when the client application get the focus. + * Implement the member function focus_in() in extended class to receive this signal. + * + * <note><para>@user_data is not actually a valid parameter. It is displayed because GtkDoc.</para></note> */ engine_signals[FOCUS_IN] = g_signal_new (I_("focus-in"), @@ -260,7 +264,9 @@ ibus_engine_class_init (IBusEngineClass *klass) * @engine: An IBusEngine. * * Emitted when the client application lost the focus. - * Implement this function in extended class to receive this signal. + * Implement the member function focus_out() in extended class to receive this signal. + * + * <note><para>@user_data is not actually a valid parameter. It is displayed because GtkDoc.</para></note> */ engine_signals[FOCUS_OUT] = g_signal_new (I_("focus-out"), @@ -277,7 +283,9 @@ ibus_engine_class_init (IBusEngineClass *klass) * @engine: An IBusEngine. * * Emitted when the IME is reset. - * Implement this function in extended class to receive this signal. + * Implement the member function reset() in extended class to receive this signal. + * + * <note><para>@user_data is not actually a valid parameter. It is displayed because GtkDoc.</para></note> */ engine_signals[RESET] = g_signal_new (I_("reset"), @@ -294,7 +302,9 @@ ibus_engine_class_init (IBusEngineClass *klass) * @engine: An IBusEngine. * * Emitted when the IME is enabled. - * Implement this function in extended class to receive this signal. + * Implement the member function set_enable() in extended class to receive this signal. + * + * <note><para>@user_data is not actually a valid parameter. It is displayed because GtkDoc.</para></note> */ engine_signals[ENABLE] = g_signal_new (I_("enable"), @@ -311,7 +321,9 @@ ibus_engine_class_init (IBusEngineClass *klass) * @engine: An IBusEngine. * * Emitted when the IME is disabled. - * Implement this function in extended class to receive this signal. + * Implement the member function set_disable() in extended class to receive this signal. + * + * <note><para>@user_data is not actually a valid parameter. It is displayed because GtkDoc.</para></note> */ engine_signals[DISABLE] = g_signal_new (I_("disable"), @@ -328,7 +340,9 @@ ibus_engine_class_init (IBusEngineClass *klass) * @engine: An IBusEngine. * * Emitted when the location of IME is set. - * Implement this functionin extended class to receive this signal. + * Implement the member function set_cursor_location() in extended class to receive this signal. + * + * <note><para>@user_data is not actually a valid parameter. It is displayed because GtkDoc.</para></note> */ engine_signals[SET_CURSOR_LOCATION] = g_signal_new (I_("set-cursor-location"), @@ -347,9 +361,12 @@ ibus_engine_class_init (IBusEngineClass *klass) /** * IBusEngine::set-capabilities: * @engine: An IBusEngine. + * @caps: Capabilities flags of IBusEngine, see #IBusCapabilite * * Emitted when the client application capabilities is set. - * Implement this function in extended class to receive this signal. + * Implement the member function set_capabilities() in extended class to receive this signal. + * + * <note><para>@user_data is not actually a valid parameter. It is displayed because GtkDoc.</para></note> */ engine_signals[SET_CAPABILITIES] = g_signal_new (I_("set-capabilities"), @@ -367,7 +384,9 @@ ibus_engine_class_init (IBusEngineClass *klass) * @engine: An IBusEngine. * * Emitted when the page-up key is pressed. - * Implement this function in extended class to receive this signal. + * Implement the member function page_up() in extended class to receive this signal. + * + * <note><para>@user_data is not actually a valid parameter. It is displayed because GtkDoc.</para></note> */ engine_signals[PAGE_UP] = g_signal_new (I_("page-up"), @@ -384,7 +403,9 @@ ibus_engine_class_init (IBusEngineClass *klass) * @engine: An IBusEngine. * * Emitted when the page-down key is pressed. - * Implement this function extend class to receive this signal. + * Implement the member function page_down() in extended class to receive this signal. + * + * <note><para>@user_data is not actually a valid parameter. It is displayed because GtkDoc.</para></note> */ engine_signals[PAGE_DOWN] = g_signal_new (I_("page-down"), @@ -401,7 +422,9 @@ ibus_engine_class_init (IBusEngineClass *klass) * @engine: An IBusEngine. * * Emitted when the up cursor key is pressed. - * Implement this function in extended class to receive this signal. + * Implement the member function cursor_up() in extended class to receive this signal. + * + * <note><para>@user_data is not actually a valid parameter. It is displayed because GtkDoc.</para></note> */ engine_signals[CURSOR_UP] = g_signal_new (I_("cursor-up"), @@ -418,7 +441,9 @@ ibus_engine_class_init (IBusEngineClass *klass) * @engine: An IBusEngine. * * Emitted when the down cursor key is pressed. - * Implement this function in extended class to receive this signal. + * Implement the member function cursor_down() in extended class to receive this signal. + * + * <note><para>@user_data is not actually a valid parameter. It is displayed because GtkDoc.</para></note> */ engine_signals[CURSOR_DOWN] = g_signal_new (I_("cursor-down"), @@ -435,7 +460,9 @@ ibus_engine_class_init (IBusEngineClass *klass) * @engine: An IBusEngine. * * Emitted when a property is activated or change changed. - * Implement this function in extended class to receive this signal. + * Implement the member function property_activate() in extended class to receive this signal. + * + * <note><para>@user_data is not actually a valid parameter. It is displayed because GtkDoc.</para></note> */ engine_signals[PROPERTY_ACTIVATE] = g_signal_new (I_("property-activate"), @@ -454,7 +481,9 @@ ibus_engine_class_init (IBusEngineClass *klass) * @engine: An IBusEngine. * * Emitted when a property is shown. - * Implement this function in extended class to receive this signal. + * Implement the member function property_side() in extended class to receive this signal. + * + * <note><para>@user_data is not actually a valid parameter. It is displayed because GtkDoc.</para></note> */ engine_signals[PROPERTY_SHOW] = g_signal_new (I_("property-show"), @@ -472,7 +501,9 @@ ibus_engine_class_init (IBusEngineClass *klass) * @engine: An IBusEngine. * * Emitted when a property is hidden. - * Implement this function in extended class to receive this signal. + * Implement the member function property_hide() in extended class to receive this signal. + * + * <note><para>@user_data is not actually a valid parameter. It is displayed because GtkDoc.</para></note> */ engine_signals[PROPERTY_HIDE] = g_signal_new (I_("property-hide"), diff --git a/src/ibuserror.h b/src/ibuserror.h index 05733d5..05a25a9 100644 --- a/src/ibuserror.h +++ b/src/ibuserror.h @@ -17,6 +17,14 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION: ibuserror + * @short_description: Error message output. + * @stability: Stable + * + * An IBusError is actually a #DBusError. + * Functions listed here are convenient wrapper for IBusError new and free. + */ #ifndef __IBUS_ERROR_H_ #define __IBUS_ERROR_H_ @@ -25,16 +33,63 @@ G_BEGIN_DECLS +/** + * IBusError: + * + * A data type representing an IBusError. + * An IBusError is actually a #DBusError. + * + * @see_also: #DBusError for detail structure definition. + */ typedef DBusError IBusError; +/** + * ibus_error_new: + * @returns: A newly allocated IBusError. + * + * New an empty IBusError. + */ IBusError *ibus_error_new (void); + +/** + * ibus_error_new_from_text: + * @name: The error name. + * @message: Detailed error message. + * @returns: A newly allocated IBusError. + * + * New an IBusError from error name and message. + */ IBusError *ibus_error_new_from_text (const gchar *name, const gchar *message); + +/** + * ibus_error_new_from_printf: + * @name: The error name. + * @format_message: printf() formatted error message. + * @returns: A newly allocated IBusError. + * + * New an IBusError from error name and a printf-formatted message. + */ IBusError *ibus_error_new_from_printf (const gchar *name, const gchar *format_message, ...); + +/** + * ibus_error_new_from_message: + * @message: A DBusMessage + * @returns: A newly allocated IBusError. + * + * New an IBusError from a #DBusMessage. + */ IBusError *ibus_error_new_from_message (DBusMessage *message); + +/** + * ibus_error_free: + * @error: An IBusError + * + * Free an IBusError. + */ void ibus_error_free (IBusError *error); G_END_DECLS diff --git a/src/ibusfactory.h b/src/ibusfactory.h index 02c883c..8fef180 100644 --- a/src/ibusfactory.h +++ b/src/ibusfactory.h @@ -17,6 +17,16 @@ * Free Software Foundation, Inc., 59 Temple Place - Suite 330, * Boston, MA 02111-1307, USA. */ +/** + * SECTION: ibusfactory + * @short_description: Factory for creating engine instances. + * @stability: Stable + * @see_also: #IBusEngine + * + * An IBusFactory is an #IBusService that creates input method engine (IME) instance. + * It provides CreateEngine remote method, which creates an IME instance by name, + * and returns the D-Bus object path to IBus daemon. + */ #ifndef __IBUS_FACTORY_H_ #define __IBUS_FACTORY_H_ @@ -63,6 +73,11 @@ typedef struct _IBusFactoryClass IBusFactoryClass; typedef struct _IBusFactoryInfo IBusFactoryInfo; typedef struct _IBusFactoryInfoClass IBusFactoryInfoClass; +/** + * IBusFactory: + * + * An opaque data type representing an IBusFactory. + */ struct _IBusFactory { IBusService parent; @@ -79,10 +94,23 @@ struct _IBusFactoryClass { gpointer pdummy[8]; }; +/** + * IBusFactoryInfo: + * @path: D-Bus path for the IME. + * @name: D-Bus name for the IME. + * @lang: Supporting language of the IME. + * @icon: Icon file of the IME. + * @authors: Authors of the IME. + * @credits: Credits of the IME. + * + * An IBusFactoryInfo stores information about an IME. + * So CreateEngine method can create instances of that IME. + */ struct _IBusFactoryInfo { IBusSerializable parent; /* instance members */ + /*< public >*/ gchar *path; gchar *name; gchar *lang; @@ -102,12 +130,52 @@ struct _IBusFactoryInfoClass { }; GType ibus_factory_get_type (void); + +/** + * ibus_factory_new: + * @connection: An IBusConnection. + * @returns: A newly allocated IBusFactory. + * + * New an IBusFactory. + */ IBusFactory *ibus_factory_new (IBusConnection *connection); + +/** + * ibus_factory_add_engine: + * @connection: An IBusConnection. + * @engine_name: Name of an engine. + * @engine_type: GType of an engine. + * + * Add an engine to the factory. + */ void ibus_factory_add_engine (IBusFactory *factory, const gchar *engine_name, GType engine_type); + +/** + * ibus_factory_get_info: + * @factory: An IBusFactory + * @returns: A corresponding IbusFactoryInfo. + * + * Get IBusFactoryInfo out of IBusFactory. + * + * <note><para>This function is currently commented out</para></note> + */ IBusFactoryInfo *ibus_factory_get_info (IBusFactory *factory); GType ibus_factory_info_get_type (void); + +/** + * ibus_factory_info_new: + * @path: D-Bus path for the IME. + * @name: IME name. + * @lang: Supporting language of the IME. + * @icon: Icon file of the IME. + * @authors: Authors of the IME. + * @credits: Credits of the IME. + * @returns: A newly allocated IBusFactoryInfo. + * + * New an IBusFactoryInfo. + */ IBusFactoryInfo *ibus_factory_info_new (const gchar *path, const gchar *name, const gchar *lang,