More cleanup.

1 files changed, 40 insertions, 3 deletions

diff --git a/sleekxmpp/roster.py b/sleekxmpp/roster.py
index 77d2131d..48f52de1 100644
--- a/sleekxmpp/roster.py
+++ b/sleekxmpp/roster.py
@@ -364,9 +364,20 @@ class RosterItem(object):
 
     def __init__(self, xmpp, jid, owner=None,
                  state=None, db=None):
+        """
+        Create a new roster item.
+
+        Arguments:
+            xmpp  -- The main SleekXMPP instance.
+            jid   -- The item's JID.
+            owner -- The roster owner's JID. Defaults
+                     so self.xmpp.boundjid.bare.
+            state -- A dictionary of initial state values.
+            db    -- An optional interface to an external datastore.
+        """
         self.xmpp = xmpp
         self.jid = jid
-        self.owner = owner or self.xmpp.jid
+        self.owner = owner or self.xmpp.boundjid.bare
         self.last_status = None
         self.resources = {}
         self.db = db
@@ -383,6 +394,10 @@ class RosterItem(object):
         self.load()
 
     def load(self):
+        """
+        Load the item's state information from an external datastore,
+        if one has been provided.
+        """
         if self.db:
             item = self.db.load(self.owner, self.jid,
                                        self._db_state)
@@ -399,11 +414,16 @@ class RosterItem(object):
         return None
 
     def save(self):
+        """
+        Save the item's state information to an external datastore,
+        if one has been provided.
+        """
         if self.db:
             self.db.save(self.owner, self.jid,
                          self._state, self._db_state)
 
     def __getitem__(self, key):
+        """Return a state field's value."""
         if key in self._state:
             if key == 'subscription':
                 return self._subscription()
@@ -412,6 +432,16 @@ class RosterItem(object):
             raise KeyError
 
     def __setitem__(self, key, value):
+        """
+        Set the value of a state field.
+
+        For boolean states, the values True, 'true', '1', 'on',
+        and 'yes' are accepted as True; all others are False.
+
+        Arguments:
+            key   -- The state field to modify.
+            value -- The new value of the state field.
+        """
         print "%s: %s" % (key, value)
         if key in self._state:
             if key in ['name', 'subscription', 'groups']:
@@ -423,6 +453,7 @@ class RosterItem(object):
             raise KeyError
 
     def _subscription(self):
+        """Return the proper subscription type based on current state."""
         if self['to'] and self['from']:
             return 'both'
         elif self['from']:
@@ -434,8 +465,8 @@ class RosterItem(object):
 
     def remove(self):
         """
-        Remove the jids subscription, inform it if it is
-        subscribed, and unwhitelist it.
+        Remove a JID's whitelisted status and unsubscribe if a 
+        subscription exists.
         """
         if self['to']:
             p = self.xmpp.Presence()
@@ -449,6 +480,7 @@ class RosterItem(object):
         self.save()
 
     def subscribe(self):
+        """Send a subscription request to the JID."""
         p = self.xmpp.Presence()
         p['to'] = self.jid
         p['type'] = 'subscribe'
@@ -459,6 +491,7 @@ class RosterItem(object):
         p.send()
 
     def authorize(self):
+        """Authorize a received subscription request from the JID."""
         self['from'] = True
         self['pending_in'] = False
         self.save()
@@ -466,6 +499,7 @@ class RosterItem(object):
         self.send_last_presence()
 
     def unauthorize(self):
+        """Deny a received subscription request from the JID."""
         self['from'] = False
         self['pending_in'] = False
         self.save()
@@ -478,6 +512,7 @@ class RosterItem(object):
         p.send()
 
     def _subscribed(self):
+        """Handle acknowledging a subscription."""
         p = self.xmpp.Presence()
         p['to'] = self.jid
         p['type'] = 'subscribed'
@@ -486,6 +521,7 @@ class RosterItem(object):
         p.send()
 
     def unsubscribe(self):
+        """Unsubscribe from the JID."""
         p = self.xmpp.Presence()
         p['to'] = self.jid
         p['type'] = 'unsubscribe'
@@ -495,6 +531,7 @@ class RosterItem(object):
         p.send()
 
     def _unsubscribed(self):
+        """Handle acknowledging an unsubscribe request."""
         p = self.xmpp.Presence()
         p['to'] = self.jid
         p['type'] = 'unsubscribed'