Add explanatory comments, etc.

5 files changed, 171 insertions, 5 deletions

diff --git a/docs/examples/glib_blinkenlight_observer/channel.c b/docs/examples/glib_blinkenlight_observer/channel.c
index 6c20e14..db8df1a 100644
--- a/docs/examples/glib_blinkenlight_observer/channel.c
+++ b/docs/examples/glib_blinkenlight_observer/channel.c
@@ -1,3 +1,27 @@
+/*
+ * channel.c - wraps TpChannel to do preparation and unread message counting
+ *             for a single channel we're observing
+ *
+ * Copyright (C) 2010 Collabora Ltd. <http://www.collabora.co.uk/>
+ *
+ * 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 St, Fifth Floor, Boston, MA  02110-1301  USA
+ *
+ * Authors:
+ *   Danielle Madeley <danielle.madeley@collabora.co.uk>
+ */
+
 #include <telepathy-glib/telepathy-glib.h>
 
 #include "channel.h"
@@ -28,7 +52,7 @@ _channel_update_pending_msgs (Channel *self)
 {
   ChannelPrivate *priv = GET_PRIVATE (self);
 
-  g_print ("%s: pending messages %u\n",
+  g_debug ("%s: pending messages %u",
       tp_proxy_get_object_path (self),
       tp_intset_size (priv->pending));
 
@@ -48,6 +72,15 @@ _channel_msg_received (TpChannel *self,
 {
   ChannelPrivate *priv = GET_PRIVATE (self);
 
+  /* The id is a number assigned to each message in the channel that is used
+   * to acknowledge the message. Messages are acknowledged by the Handler when
+   * it is sure that the user has seen them. When the client acknowledges a
+   * message, we will receive the signal PendingMessageRemoved, and we can
+   * remove this id from our pending list.
+   *
+   * For this to work it requires a well-behaved client that doesn't just
+   * acknowledge messages immediately. For instance, recent Empathy */
+
   if (type == TP_CHANNEL_TEXT_MESSAGE_TYPE_NORMAL)
     {
       tp_intset_add (priv->pending, id);
@@ -65,6 +98,9 @@ _channel_pending_msg_removed (TpChannel *self,
   ChannelPrivate *priv = GET_PRIVATE (self);
   guint i;
 
+  /* The client has acknowledged @ids, and we can remove them from the list
+   * of messages we know the user hasn't seen */
+
   for (i = 0; i < ids->len; i++)
     {
       guint id = g_array_index (ids, guint, i);
@@ -88,6 +124,7 @@ _channel_list_pending_messages (TpChannel *self,
     {
       guint i;
 
+      /* Iterate the pending messages */
       for (i = 0; i < messages->len; i++)
         {
           guint id, timestamp, sender, type, flags;
@@ -101,7 +138,12 @@ _channel_list_pending_messages (TpChannel *self,
               NULL, NULL);
         }
     }
+  else
+    {
+      g_warning ("Failed to get pending messages: %s", error->message);
+    }
 
+  /* call the readiness callback */
   data->callback (self, error, data->user_data);
   g_slice_free (ReadyCallbackData, data);
 }
@@ -114,11 +156,19 @@ _channel_ready (TpChannel *self,
   ReadyCallbackData *data = user_data;
   GError *lerror = NULL;
 
+  if (error != NULL)
+    {
+      data->callback (self, error, data->user_data);
+      g_slice_free (ReadyCallbackData, data);
+      return;
+    }
+
   /* get the pending messages on the channel */
   tp_cli_channel_type_text_call_list_pending_messages (self, -1, FALSE,
       _channel_list_pending_messages,
       data, NULL, NULL);
 
+  /* connect to the signals we need to listen to */
   tp_cli_channel_type_text_connect_to_received (self,
       _channel_msg_received,
       NULL, NULL, NULL, &lerror);
@@ -140,6 +190,7 @@ channel_call_when_ready (Channel *self,
   data->callback = callback;
   data->user_data = user_data;
 
+  /* prepare the TpChannel */
   tp_channel_call_when_ready (TP_CHANNEL (self), _channel_ready, data);
 }
 
@@ -209,6 +260,8 @@ channel_new (TpConnection *conn,
     const GHashTable *properties,
     GError **error)
 {
+  /* this function is copied from
+   * telepathy-glib/channel.c:tp_channel_new_from_properties */
   Channel *self = NULL;
 
   g_return_val_if_fail (TP_IS_CONNECTION (conn), NULL);
diff --git a/docs/examples/glib_blinkenlight_observer/channel.h b/docs/examples/glib_blinkenlight_observer/channel.h
index 2949149..4447b22 100644
--- a/docs/examples/glib_blinkenlight_observer/channel.h
+++ b/docs/examples/glib_blinkenlight_observer/channel.h
@@ -1,3 +1,27 @@
+/*
+ * channel.h - wraps TpChannel to do preparation and unread message counting
+ *             for a single channel we're observing
+ *
+ * Copyright (C) 2010 Collabora Ltd. <http://www.collabora.co.uk/>
+ *
+ * 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 St, Fifth Floor, Boston, MA  02110-1301  USA
+ *
+ * Authors:
+ *   Danielle Madeley <danielle.madeley@collabora.co.uk>
+ */
+
 #ifndef __CHANNEL_H__
 #define __CHANNEL_H__
 
diff --git a/docs/examples/glib_blinkenlight_observer/main.c b/docs/examples/glib_blinkenlight_observer/main.c
index 06f310d..4a97d8d 100644
--- a/docs/examples/glib_blinkenlight_observer/main.c
+++ b/docs/examples/glib_blinkenlight_observer/main.c
@@ -1,3 +1,26 @@
+/*
+ * main.c - creates the Observer and registers it on the bus
+ *
+ * Copyright (C) 2010 Collabora Ltd. <http://www.collabora.co.uk/>
+ *
+ * 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 St, Fifth Floor, Boston, MA  02110-1301  USA
+ *
+ * Authors:
+ *   Danielle Madeley <danielle.madeley@collabora.co.uk>
+ */
+
 #include <glib.h>
 #include <dbus/dbus-glib.h>
 
@@ -28,7 +51,7 @@ main (int argc, char **argv)
   g_assert (tp_dbus_daemon_request_name (tpdbus,
       TP_CLIENT_BUS_NAME_BASE CLIENT_NAME,
       TRUE, NULL));
-  /* register ExampleObserver on the bus */
+  /* register observer on the bus */
   dbus_g_connection_register_g_object (dbus,
       TP_CLIENT_OBJECT_PATH_BASE CLIENT_NAME,
       G_OBJECT (observer));
diff --git a/docs/examples/glib_blinkenlight_observer/observer.c b/docs/examples/glib_blinkenlight_observer/observer.c
index a34bff1..bcace27 100644
--- a/docs/examples/glib_blinkenlight_observer/observer.c
+++ b/docs/examples/glib_blinkenlight_observer/observer.c
@@ -1,3 +1,27 @@
+/*
+ * observer.c - a Telepathy Observer, observes text channels to count their
+ *              unread messages
+ *
+ * Copyright (C) 2010 Collabora Ltd. <http://www.collabora.co.uk/>
+ *
+ * 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 St, Fifth Floor, Boston, MA  02110-1301  USA
+ *
+ * Authors:
+ *   Danielle Madeley <danielle.madeley@collabora.co.uk>
+ */
+
 #include <telepathy-glib/telepathy-glib.h>
 #include <telepathy-glib/svc-generic.h>
 #include <telepathy-glib/svc-client.h>
@@ -59,6 +83,7 @@ _update_count (Observer *self)
       total += unread;
     }
 
+  /* this is where code to interface with the blinking light/whatever goes */
   g_print ("TOTAL UNREAD MESSAGES: %u\n", total);
 }
 
@@ -79,8 +104,9 @@ _channel_closed (TpProxy *channel,
 {
   ObserverPrivate *priv = GET_PRIVATE (self);
 
-  g_print ("Channel closed: %s\n", tp_proxy_get_object_path (channel));
+  g_debug ("Channel closed: %s", tp_proxy_get_object_path (channel));
 
+  /* remove this channel from the list of active channels */
   priv->channels = g_list_remove (priv->channels, channel);
   _update_count (self);
 
@@ -96,12 +122,14 @@ _channel_ready (TpChannel *channel,
   Observer *self = data->self;
   ObserverPrivate *priv = GET_PRIVATE (self);
 
+  /* remove the channel from the pending list */
   data->pending = g_list_remove (data->pending, channel);
 
   if (error == NULL)
     {
-      g_print ("Channel ready: %s\n", tp_proxy_get_object_path (channel));
+      g_debug ("Channel ready: %s", tp_proxy_get_object_path (channel));
 
+      /* put this channel in the list of active channels */
       priv->channels = g_list_prepend (priv->channels, channel);
 
       tp_g_signal_connect_object (channel, "notify::unread",
@@ -113,14 +141,19 @@ _channel_ready (TpChannel *channel,
     }
   else
     {
+      g_warning ("Channel ready failed: %s",
+          tp_proxy_get_object_path (channel));
+
       /* drop the ref, this channel is dead */
       g_object_unref (channel);
     }
 
   if (data->pending == NULL)
     {
-      g_print ("All channels ready\n");
+      g_debug ("All channels ready");
 
+      /* if all channels for this dispatch are ready, we can return from
+       * ObserveChannels */
       tp_svc_client_observer_return_from_observe_channels (data->context);
 
       g_slice_free (ReadyCallbackData, data);
@@ -151,6 +184,10 @@ observer_observe_channels (TpSvcClientObserver *self,
   if (error != NULL)
     goto error;
 
+  /* returning from the D-Bus method ObserveChannels passes the channels
+   * onwards towards the Handler. We want to have the chance to read the
+   * initial pending message queue before it gets acknowledged, so we defer
+   * returning from ObserveChannels until all the channels are ready */
   data = g_slice_new0 (ReadyCallbackData);
   data->self = OBSERVER (self);
   data->context = context;
@@ -170,6 +207,8 @@ observer_observe_channels (TpSvcClientObserver *self,
       if (error != NULL)
         continue;
 
+      /* place this channel in the list of channels pending preparation
+       * for this dispatch */
       data->pending = g_list_prepend (data->pending, chan);
       channel_call_when_ready (chan, _channel_ready, data);
     }
@@ -205,6 +244,7 @@ observer_get_property (GObject *self,
         {
           GPtrArray *array = g_ptr_array_new ();
 
+          /* Observe all text channels */
           g_ptr_array_add (array, tp_asv_new (
                 TP_IFACE_CHANNEL ".ChannelType",
                 G_TYPE_STRING,
@@ -240,6 +280,8 @@ observer_class_init (ObserverClass *klass)
   /* properties on the Client.Observer interface */
   static TpDBusPropertiesMixinPropImpl client_observer_props[] = {
         { "ObserverChannelFilter", "channel-filter", NULL },
+        /* NB: eventually we'll want to support the Recover property:
+         *     https://bugs.freedesktop.org/show_bug.cgi?id=24768 */
         { NULL }
   };
 
diff --git a/docs/examples/glib_blinkenlight_observer/observer.h b/docs/examples/glib_blinkenlight_observer/observer.h
index 07079c6..1f3015b 100644
--- a/docs/examples/glib_blinkenlight_observer/observer.h
+++ b/docs/examples/glib_blinkenlight_observer/observer.h
@@ -1,3 +1,27 @@
+/*
+ * observer.h - a Telepathy Observer, observes text channels to count their
+ *              unread messages
+ *
+ * Copyright (C) 2010 Collabora Ltd. <http://www.collabora.co.uk/>
+ *
+ * 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 St, Fifth Floor, Boston, MA  02110-1301  USA
+ *
+ * Authors:
+ *   Danielle Madeley <danielle.madeley@collabora.co.uk>
+ */
+
 #ifndef __OBSERVER_H__
 #define __OBSERVER_H__