Documentation for the activity and buddy presence objects

1 files changed, 44 insertions, 1 deletions

diff --git a/sugar/presence/activity.py b/sugar/presence/activity.py
index 1616378..f290368 100644
--- a/sugar/presence/activity.py
+++ b/sugar/presence/activity.py
@@ -1,3 +1,4 @@
+"""UI interface to an activity in the presence service"""
 # Copyright (C) 2007, Red Hat, Inc.
 #
 # This library is free software; you can redistribute it and/or
@@ -19,7 +20,19 @@ import gobject
 import dbus
 
 class Activity(gobject.GObject):
-
+    """UI interface for an Activity in the presence service
+    
+    Activities in the presence service represent other user's
+    shared activities and your own activities (XXX shared or 
+    otherwise?)
+    
+    Properties:
+        id 
+        color 
+        name 
+        type 
+        joined 
+    """
     __gsignals__ = {
         'buddy-joined': (gobject.SIGNAL_RUN_FIRST, gobject.TYPE_NONE,
                          ([gobject.TYPE_PYOBJECT])),
@@ -33,6 +46,7 @@ class Activity(gobject.GObject):
     _ACTIVITY_DBUS_INTERFACE = "org.laptop.Sugar.Presence.Activity"
 
     def __init__(self, bus, new_obj_cb, del_obj_cb, object_path):
+        """Initialse the activity interface, connecting to service"""
         gobject.GObject.__init__(self)
         self._object_path = object_path
         self._ps_new_object = new_obj_cb
@@ -50,9 +64,11 @@ class Activity(gobject.GObject):
         self._joined = False
 
     def object_path(self):
+        """Get our dbus object path"""
         return self._object_path
 
     def _emit_buddy_joined_signal(self, object_path):
+        """Generate buddy-joined GObject signal with presence Buddy object"""
         self.emit('buddy-joined', self._ps_new_object(object_path))
         return False
 
@@ -60,6 +76,10 @@ class Activity(gobject.GObject):
         gobject.idle_add(self._emit_buddy_joined_signal, object_path)
 
     def _emit_buddy_left_signal(self, object_path):
+        """Generate buddy-left GObject signal with presence Buddy object
+        
+        XXX note use of _ps_new_object instead of _ps_del_object here
+        """
         self.emit('buddy-left', self._ps_new_object(object_path))
         return False
 
@@ -67,6 +87,10 @@ class Activity(gobject.GObject):
         gobject.idle_add(self._emit_buddy_left_signal, object_path)
 
     def _emit_new_channel_signal(self, object_path):
+        """Generate new-channel GObject signal with channel object path 
+        
+        New telepathy-python communications channel has been opened
+        """
         self.emit('new-channel', object_path)
         return False
 
@@ -74,27 +98,35 @@ class Activity(gobject.GObject):
         gobject.idle_add(self._emit_new_channel_signal, object_path)
 
     def get_id(self):
+        """Retrieve the unique identifier for this activity instance"""
         # Cache activity ID, which should never change anyway
         if not self._id:
             self._id = self._activity.GetId()
         return self._id
 
     def get_color(self):
+        """Retrieve the activity icon colour for this activity instance"""
         if not self._color:
             self._color = self._activity.GetColor()
         return self._color
 
     def get_name(self):
+        """Retrieve the activity name for this activity instance"""
         if not self._name:
             self._name = self._activity.GetName()
         return self._name
 
     def get_type(self):
+        """Retrieve the activity/bundle type for this activity instance"""
         if not self._type:
             self._type = self._activity.GetType()
         return self._type
 
     def get_joined_buddies(self):
+        """Retrieve the set of Buddy objects attached to this activity
+        
+        returns list of presence Buddy objects
+        """
         resp = self._activity.GetJoinedBuddies()
         buddies = []
         for item in resp:
@@ -102,15 +134,26 @@ class Activity(gobject.GObject):
         return buddies
 
     def join(self):
+        """Join this activity 
+        
+        XXX if these are all activities, can I join my own activity?
+        """
         if self._joined:
             return
         self._activity.Join()
         self._joined = True
 
     def get_channels(self):
+        """Retrieve communications channel descriptions for the activity 
+        
+        Returns (bus name, connection, channels) for the activity
+        
+        XXX what are those values?
+        """
         (bus_name, connection, channels) = self._activity.GetChannels()
         return bus_name, connection, channels
 
     def owner_has_joined(self):
+        """Retrieve whether the owner of the activity is active within it"""
         # FIXME
         return False