soc.2009.telepathy: 1b740d4c: Documented telepathy_channel.*

[sttwister at gmail.com]

-----------------------------------------------------------------
Revision: 1b740d4c16fcab78970f88764b04a7ae4d014021
Ancestor: 6d6c740a338f994a1cbda3b805b856fd557e0fb7
Author: sttwister at gmail.com
Date: 2009-12-22T00:00:08
Branch: im.pidgin.soc.2009.telepathy
URL: http://d.pidgin.im/viewmtn/revision/info/1b740d4c16fcab78970f88764b04a7ae4d014021

Modified files:
        libpurple/protocols/telepathy/telepathy_channel.c
        libpurple/protocols/telepathy/telepathy_channel.h

ChangeLog: 

Documented telepathy_channel.*

-------------- next part --------------
============================================================
--- libpurple/protocols/telepathy/telepathy_channel.c	e70b5e1d3c491928832d39886fa5935de4e837ac
+++ libpurple/protocols/telepathy/telepathy_channel.c	23cdd792b3d84cb2b38215e14d89c25b0d13b584
@@ -33,6 +33,9 @@
 #include "telepathy_channel_text.h"
 #include "telepathy_contact.h"
 
+/**
+ * Callback for the Proceed DBus method.
+ */
 static void
 proceed_cb (TpChannelRequest *proxy,
             const GError *error,
@@ -80,6 +83,7 @@ create_channel_cb (TpChannelDispatcher *
 		return;
 	}
 
+	/* Create a channel request object */
 	request = tp_channel_request_new(bus_daemon, out_Request, NULL, &err);
 
 	if (err != NULL)
@@ -92,6 +96,7 @@ create_channel_cb (TpChannelDispatcher *
 		return;
 	}
 
+	/* Finalize the creation by calling Proceed on the request object */
 	tp_cli_channel_request_call_proceed(request, -1, proceed_cb, user_data, NULL, NULL);
 }
 
@@ -142,6 +147,7 @@ handle_new_channel (PrplTpConnection *da
 	g_return_if_fail(data != NULL);
 	g_return_if_fail(channel_Properties != NULL);
 
+	/* Extract the object path and properties map. */
 	char *object_Path = g_value_get_boxed(g_value_array_get_nth((GValueArray *)channel_Properties, 0));
 	GHashTable *map = g_value_get_boxed(g_value_array_get_nth((GValueArray *)channel_Properties, 1));
 
@@ -166,6 +172,7 @@ handle_new_channel (PrplTpConnection *da
 		return;
 	}
 
+	/* Create a channel proxy object using the object path and properties map. */
 	channel = tp_channel_new_from_properties(connection, object_Path, map, &error);
 
 	if (error != NULL)
@@ -177,6 +184,7 @@ handle_new_channel (PrplTpConnection *da
 	
 	purple_debug_info("telepathy", "New channel: %s\n", object_Path);
 
+	/* Make sure the channel is ready before taking any further action. */
 	tp_channel_call_when_ready(channel, channel_ready_cb, data);
 
 	g_signal_connect(channel, "invalidated", G_CALLBACK (channel_invalidated_cb), data);
============================================================
--- libpurple/protocols/telepathy/telepathy_channel.h	570239286a30824ced924971617e215db01c7750
+++ libpurple/protocols/telepathy/telepathy_channel.h	a6fcdd9739f574b0d9fa19f75fed99fd2953342b
@@ -28,6 +28,17 @@
 
 #include "telepathy_connection.h"
 
+/**
+ * Callback for the CreateChannel DBus method.
+ *
+ * Calls Proceed on the returned channel request object in order to finalize
+ * the creation.
+ *
+ * @param proxy       The channel dispatcher proxy.
+ * @param out_Request Object path to a channel request object.
+ * @param error       Points to a GError on failure, @c NULL otherwise.
+ * @param user_data   Points to a #PrplTpConnection.
+ */
 void
 create_channel_cb (TpChannelDispatcher *proxy,
                    const gchar *out_Request,
@@ -35,11 +46,23 @@ create_channel_cb (TpChannelDispatcher *
                    gpointer user_data,
                    GObject *weak_object);
 
+/**
+ * Called when a channel is ready.
+ *
+ * Checks the type of the channel and takes action accordingly.
+ *
+ * @param channel   The channel proxy object.
+ * @param error     Points to a GError on failure, @c NULL otherwise.
+ * @param user_data Points to a #PrplTpConnection.
+ */
 void
 channel_ready_cb (TpChannel *channel,
                   const GError *error,
                   gpointer user_data);
 
+/**
+ * Callback for the TpChannel's "invalidated" GObject signal.
+ */
 void
 channel_invalidated_cb (TpProxy *self,
                         guint    domain,
@@ -47,16 +70,39 @@ channel_invalidated_cb (TpProxy *self,
                         gchar   *message,
                         gpointer user_data);
 
+/**
+ * Prepares an incoming channel received by the NewChannels DBus signal.
+ *
+ * Drops the channel if it's not a contact list, as any other channel should be
+ * handled by the Client interface.
+ *
+ * @param data               The connection on which the channel was created.
+ * @param channel_Properties An array containing the channel properties
+ *                           represented as an (oa{sv}) DBus type.
+ */
 void
 handle_new_channel (PrplTpConnection *data,
                     const GValueArray *channel_Properties);
 
+/**
+ * Callback for the NewChannels DBus signal.
+ */
 void
 new_channels_cb (TpConnection *proxy,
                  const GPtrArray *arg_Channels,
                  gpointer user_data,
                  GObject *weak_object);
 
+/**
+ * Callback for getting the Connection's "Channels" DBus property.
+ *
+ * Passes the channels to #handle_new_channel()
+ * 
+ * @param proxy     The connection proxy object.
+ * @param out_Value A GValue containing an @c a(oa{sv}) DBus type.
+ * @param error     Points to a GError on failure, @c NULL otherwise.
+ * @param user_data Points to a #PrplTpConnection.
+ */
 void
 get_channels_cb (TpProxy *proxy,
                  const GValue *out_Value,