soc.2009.telepathy: 45d8e9ee: Documented telepathy_avatar.*

[sttwister at gmail.com]

-----------------------------------------------------------------
Revision: 45d8e9eea97116e6af7ef14e42b330db396592d7
Ancestor: 8d7afbb08bd2f2b3345a36e7efaf841886ac7ae8
Author: sttwister at gmail.com
Date: 2009-12-21T23:01:55
Branch: im.pidgin.soc.2009.telepathy
URL: http://d.pidgin.im/viewmtn/revision/info/45d8e9eea97116e6af7ef14e42b330db396592d7

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

ChangeLog: 

Documented telepathy_avatar.*

-------------- next part --------------
============================================================
--- libpurple/protocols/telepathy/telepathy_avatar.c	29ea6ab5eea2dfabf13769922f4fcc5516cab407
+++ libpurple/protocols/telepathy/telepathy_avatar.c	5168e8dda9a2bc89f857dc8a1a95af7df132491f
@@ -27,6 +27,9 @@
 
 #include <string.h>
 
+/**
+ * Callback for the RequestAvatars DBus method.
+ */
 static void
 request_avatars_cb (TpConnection *proxy,
                     const GError *error,
============================================================
--- libpurple/protocols/telepathy/telepathy_avatar.h	f4c1502ee67f34dee5b5d58d4773567fa209925d
+++ libpurple/protocols/telepathy/telepathy_avatar.h	da569f0477bc861a6624e43ef2ee51bc19531538
@@ -23,6 +23,15 @@
 
 #include <telepathy-glib/connection.h>
 
+/**
+ * Callback for the GetKnownAvatarTokens DBus method.
+ *
+ * Requests a new avatar for users who don't have the current avatar cahced.
+ *
+ * @param proxy      The connection proxy object.
+ * @param out_Tokens A hash table mapping contact handles to avatar tokens.
+ * @param error      Points to a GError on failure, @c NULL otherwise.
+ */
 void
 get_known_avatar_tokens_cb (TpConnection *proxy,
                             GHashTable *out_Tokens,
@@ -30,6 +39,18 @@ get_known_avatar_tokens_cb (TpConnection
                             gpointer user_data,
                             GObject *weak_object);
 
+/**
+ * Callback for the AvatarRetrieved DBus signal.
+ *
+ * Updates the avatar for a buddy and caches it.
+ *
+ * @param proxy       The connection proxy object
+ * @param arg_Contact The handle of the contact whose avatar was retrieved.
+ * @param arg_Token   A token for the avatar used for caching.
+ * @param arg_Avata   A byte array representing the avatar.
+ * @param arg_Type    The image MIME type or empty if unknown.
+ * @param user_data   Points to a #PrplTpConnection.
+ */
 void
 avatar_retrieved_cb (TpConnection *proxy,
                      guint arg_Contact,
@@ -39,6 +60,16 @@ avatar_retrieved_cb (TpConnection *proxy
                      gpointer user_data,
                      GObject *weak_object);
 
+/**
+ * Callback for the AvatarUpdated DBus signal.
+ *
+ * Requests a the avatar for a buddy in case it's not cached.
+ *
+ * @param proxy                The connection proxy object.
+ * @param arg_Contact          The contact handle whose avatar is updated.
+ * @param arg_New_Avatar_Token A new avatar token.
+ * @param user_data            Points to a #PrplTpConnection.
+ */
 void
 avatar_updated_cb (TpConnection *proxy,
                    guint arg_Contact,
@@ -46,6 +77,16 @@ avatar_updated_cb (TpConnection *proxy,
                    gpointer user_data,
                    GObject *weak_object);
 
+/**
+ * Callback for getting all the properties of a connection's Avatar interface.
+ * 
+ * Updates libpurple's supported avatar formats.
+ *
+ * @param proxy          The connection proxy object.
+ * @param out_Properties A hash table mapping property names to values.
+ * @param error          Points to a GError in case of failure, @c NULL otherwise.
+ * @param user_data      Points to a #PrplTpConnection.
+ */
 void
 get_avatar_properties_cb (TpProxy *proxy,
                           GHashTable *out_Properties,
@@ -53,6 +94,9 @@ get_avatar_properties_cb (TpProxy *proxy
                           gpointer user_data,
                           GObject *weak_object);
 
+/**
+ * Callback for the SetAvatar DBus method.
+ */
 void
 set_avatar_cb (TpConnection *proxy,
                const gchar *out_Token,
@@ -60,7 +104,9 @@ set_avatar_cb (TpConnection *proxy,
                gpointer user_data,
                GObject *weak_object);
 
-void
+/**
+ * Callback for the ClearAvatar DBus method.
+ */
 clear_avatar_cb (TpConnection *proxy,
                  const GError *error,
                  gpointer user_data,