Add comments to ibusproxy.[ch] and related functions.

BUG=none
TEST=none

Review URL: http://codereview.appspot.com/3802042

diff --git a/bus/ibusimpl.c b/bus/ibusimpl.c
index d7e496df7d53fbae6243cb1afe625a4708c1ff6c..d985652f7e100237f2d077f9b122f1204a1f5009 100644 (file)
--- a/bus/ibusimpl.c
+++ b/bus/ibusimpl.c
@@ -251,6 +251,12 @@ bus_ibus_impl_class_init (BusIBusImplClass *class)
     ibus_service_class_add_interfaces (IBUS_SERVICE_CLASS (class), introspection_xml);
 }
 
+/**
+ * _panel_destroy_cb:
+ *
+ * A callback function which is called when (1) the connection to the panel process is terminated,
+ * or (2) ibus_proxy_destroy (ibus->panel); is called. See src/ibusproxy.c for details.
+ */
 static void
 _panel_destroy_cb (BusPanelProxy *panel,
                    BusIBusImpl   *ibus)
@@ -583,6 +589,12 @@ _config_value_changed_cb (IBusConfig  *config,
     }
 }
 
+/**
+ * _config_destroy_cb:
+ *
+ * A callback function which is called when (1) the connection to the config process is terminated,
+ * or (2) ibus_proxy_destroy (ibus->config); is called. See src/ibusproxy.c for details.
+ */
 static void
 _config_destroy_cb (IBusConfig  *config,
                     BusIBusImpl *ibus)
@@ -629,7 +641,7 @@ _dbus_name_owner_changed_cb (BusDBusImpl *dbus,
 
             if (ibus->panel != NULL) {
                 ibus_proxy_destroy ((IBusProxy *) ibus->panel);
-                /* panel should be NULL after destroy */
+                /* panel should be NULL after destroy. See _panel_destroy_cb for details. */
                 g_assert (ibus->panel == NULL);
             }
 
@@ -655,7 +667,7 @@ _dbus_name_owner_changed_cb (BusDBusImpl *dbus,
 
             if (ibus->config != NULL) {
                 ibus_proxy_destroy ((IBusProxy *) ibus->config);
-                /* config should be NULL */
+                /* config should be NULL after destroy. See _config_destroy_cb for details. */
                 g_assert (ibus->config == NULL);
             }
 

diff --git a/src/ibusproxy.c b/src/ibusproxy.c
index 1516c34748c6a390f0af6f426d56dffad71578df..0bae0d70d096c1ed62864b6f058062a63a9d453e 100644 (file)
--- a/src/ibusproxy.c
+++ b/src/ibusproxy.c
@@ -100,6 +100,11 @@ ibus_proxy_constructed (GObject *object)
     /* FIXME add match rules? */
 }
 
+/**
+ * ibus_proxy_dispose:
+ *
+ * Override GObject's dispose function.
+ */
 static void
 ibus_proxy_dispose (GObject *object)
 {
@@ -115,6 +120,11 @@ ibus_proxy_dispose (GObject *object)
     G_OBJECT_CLASS(ibus_proxy_parent_class)->dispose (object);
 }
 
+/**
+ * ibus_proxy_real_destroy:
+ *
+ * Handle "destroy" signal which is emitted by ibus_proxy_dispose.
+ */
 static void
 ibus_proxy_real_destroy (IBusProxy *proxy)
 {

diff --git a/src/ibusproxy.h b/src/ibusproxy.h
index f98e1ff4ee77fb782441f9d09fcb8da027413fc2..7584792348e82126147bc575f3ab6b3173a3e784 100644 (file)
--- a/src/ibusproxy.h
+++ b/src/ibusproxy.h
@@ -93,6 +93,15 @@ struct _IBusProxyClass {
 
 GType   ibus_proxy_get_type (void);
 
+/**
+ * ibus_proxy_destroy:
+ *
+ * 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);
 
 G_END_DECLS