Merge with Andrew

[hermes] / package / src / org / maemo / hermes / engine / facebook / service.py

diff --git a/package/src/org/maemo/hermes/engine/facebook/service.py b/package/src/org/maemo/hermes/engine/facebook/service.py
index 6fa6c68..30d24cc 100644 (file)
--- a/package/src/org/maemo/hermes/engine/facebook/service.py
+++ b/package/src/org/maemo/hermes/engine/facebook/service.py
@@ -15,9 +15,6 @@ class Service(org.maemo.hermes.engine.service.Service):
 
     # -----------------------------------------------------------------------
     def __init__(self, service_id, facebook, create_birthday_only = False):
-        """Initialise the Facebook service, finding Facebook API keys in gconf and
-           having a gui_callback available."""
-        
         self.fb = facebook
         self._service_id = service_id
         
@@ -30,32 +27,40 @@ class Service(org.maemo.hermes.engine.service.Service):
 
 
     # -----------------------------------------------------------------------
-    def get_name(self):
-        return "Facebook"
-    
-
-    # -----------------------------------------------------------------------
     def get_friends(self):
+        """Returns all friends on Facebook"""
+        
         return self._contacts_by_friend.keys()
     
     
+    # -----------------------------------------------------------------------
     def get_contacts_with_match(self):
+        """Returns a dict, where each key value pair is a contact (key) that 
+           matched a friend (value)"""
+
         return self._friends_by_contact
     
+    
+    # -----------------------------------------------------------------------
     def get_unmatched_friends(self):
+        """Returns a list of all friends that didn't match a contact."""
+         
         return self._friends_by_name.values()
 
 
     # -----------------------------------------------------------------------
     def pre_process_contact(self, contact):
-        """Registers URLs of all previous mappings, and makes sure that any Friends with those
-           URLs don't get match by name."""
+        """Registers URLs of all previous mappings, and makes sure that any 
+           friend with such a URL don't get match by name."""
+           
         for url in contact.get_urls():
             self._known_urls.add(url)
     
     
     # -----------------------------------------------------------------------
     def process_friends(self):
+        """Retreives data from Facebook and parse that into Friend 
+           objects."""
         
         def if_defined(data, key, callback):
             if key in data and data[key]:
@@ -86,6 +91,9 @@ class Service(org.maemo.hermes.engine.service.Service):
 
     # -----------------------------------------------------------------------
     def process_contact(self, contact):
+        """If the contact is matched with a friend, that friend is returned,
+           otherwise None."""
+           
         matched_friend = None
         if self._friends_by_contact.has_key(contact):
             matched_friend = self._friends_by_contact[contact]
@@ -119,6 +127,7 @@ class Service(org.maemo.hermes.engine.service.Service):
 
     # -----------------------------------------------------------------------
     def _get_friends_data(self):
-        """Returns a list of dicts, where each dict represents a friend/contact"""
+        """Returns a list of dicts, where each dict represents the raw data
+           of a friend"""
         
         return self.fb.users.getInfo(self.fb.friends.get(), Service.attrs)