More doc updates

2 files changed, 249 insertions, 279 deletions

diff --git a/sleekxmpp/basexmpp.py b/sleekxmpp/basexmpp.py
index 46626bac..ee0ae988 100644
--- a/sleekxmpp/basexmpp.py
+++ b/sleekxmpp/basexmpp.py
@@ -1,9 +1,15 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
-    Copyright (C) 2010  Nathanael C. Fritz
-    This file is part of SleekXMPP.
+    sleekxmpp.basexmpp
+    ~~~~~~~~~~~~~~~~~~
 
-    See the file LICENSE for copying permission.
+    This module provides the common XMPP functionality
+    for both clients and components.
+
+    Part of SleekXMPP: The Sleek XMPP Library
+
+    :copyright: (c) 2011 Nathanael C. Fritz
+    :license: MIT, see LICENSE for more details
 """
 
 from __future__ import with_statement, unicode_literals
@@ -43,71 +49,59 @@ class BaseXMPP(XMLStream):
     with XMPP. It also provides a plugin mechanism to easily extend
     and add support for new XMPP features.
 
-    Attributes:
-       auto_authorize   -- Manage automatically accepting roster
-                           subscriptions.
-       auto_subscribe   -- Manage automatically requesting mutual
-                           subscriptions.
-       is_component     -- Indicates if this stream is for an XMPP component.
-       jid              -- The XMPP JID for this stream.
-       plugin           -- A dictionary of loaded plugins.
-       plugin_config    -- A dictionary of plugin configurations.
-       plugin_whitelist -- A list of approved plugins.
-       sentpresence     -- Indicates if an initial presence has been sent.
-       roster           -- A dictionary containing subscribed JIDs and
-                           their presence statuses.
-
-    Methods:
-       Iq                      -- Factory for creating an Iq stanzas.
-       Message                 -- Factory for creating Message stanzas.
-       Presence                -- Factory for creating Presence stanzas.
-       get                     -- Return a plugin given its name.
-       make_iq                 -- Create and initialize an Iq stanza.
-       make_iq_error           -- Create an Iq stanza of type 'error'.
-       make_iq_get             -- Create an Iq stanza of type 'get'.
-       make_iq_query           -- Create an Iq stanza with a given query.
-       make_iq_result          -- Create an Iq stanza of type 'result'.
-       make_iq_set             -- Create an Iq stanza of type 'set'.
-       make_message            -- Create and initialize a Message stanza.
-       make_presence           -- Create and initialize a Presence stanza.
-       make_query_roster       -- Create a roster query.
-       process                 -- Overrides XMLStream.process.
-       register_plugin         -- Load and configure a plugin.
-       register_plugins        -- Load and configure multiple plugins.
-       send_message            -- Create and send a Message stanza.
-       send_presence           -- Create and send a Presence stanza.
-       send_presence_subscribe -- Send a subscription request.
+    :param default_ns: Ensure that the correct default XML namespace
+                       is used during initialization.
     """
 
     def __init__(self, jid='', default_ns='jabber:client'):
-        """
-        Adapt an XML stream for use with XMPP.
-
-        Arguments:
-            default_ns -- Ensure that the correct default XML namespace
-                          is used during initialization.
-        """
         XMLStream.__init__(self)
 
-        # To comply with PEP8, method names now use underscores.
-        # Deprecated method names are re-mapped for backwards compatibility.
         self.default_ns = default_ns
         self.stream_ns = 'http://etherx.jabber.org/streams'
         self.namespace_map[self.stream_ns] = 'stream'
 
+        #: An identifier for the stream as given by the server.
+        self.stream_id = None
+
+        #: The JabberID (JID) used by this connection. 
         self.boundjid = JID(jid)
 
+        #: A dictionary mapping plugin names to plugins.
         self.plugin = {}
+
+        #: Configuration options for whitelisted plugins.
+        #: If a plugin is registered without any configuration,
+        #: and there is an entry here, it will be used.
         self.plugin_config = {}
+
+        #: A list of plugins that will be loaded if
+        #: :meth:`register_plugins` is called.
         self.plugin_whitelist = []
 
+        #: The main roster object. This roster supports multiple
+        #: owner JIDs, as in the case for components. For clients
+        #: which only have a single JID, see :attr:`client_roster`.
         self.roster = roster.Roster(self)
         self.roster.add(self.boundjid.bare)
+
+        #: The single roster for the bound JID. This is the
+        #: equivalent of::
+        #:
+        #:     self.roster[self.boundjid.bare]
         self.client_roster = self.roster[self.boundjid.bare]
 
+        #: The distinction between clients and components can be
+        #: important, primarily for choosing how to handle the
+        #: ``'to'`` and ``'from'`` JIDs of stanzas.
         self.is_component = False
+
+        #: Flag indicating that the initial presence broadcast has
+        #: been sent. Until this happens, some servers may not
+        #: behave as expected when sending stanzas.
         self.sentpresence = False
 
+        #: A reference to :mod:`sleekxmpp.stanza` to make accessing
+        #: stanza classes easier.
         self.stanza = sleekxmpp.stanza
 
         self.register_handler(
@@ -161,40 +155,36 @@ class BaseXMPP(XMLStream):
         register_stanza_plugin(Message, HTMLIM)
 
     def start_stream_handler(self, xml):
-        """
-        Save the stream ID once the streams have been established.
-
-        Overrides XMLStream.start_stream_handler.
+        """Save the stream ID once the streams have been established.
 
-        Arguments:
-            xml -- The incoming stream's root element.
+        :param xml: The incoming stream's root element.
         """
         self.stream_id = xml.get('id', '')
 
     def process(self, *args, **kwargs):
-        """
-        Overrides XMLStream.process.
-
-        Initialize the XML streams and begin processing events.
+        """Initialize plugins and begin processing the XML stream.
 
         The number of threads used for processing stream events is determined
-        by HANDLER_THREADS.
-
-        Arguments:
-            block -- If block=False then event dispatcher will run
-                     in a separate thread, allowing for the stream to be
-                     used in the background for another application.
-                     Otherwise, process(block=True) blocks the current thread.
-                     Defaults to False.
-
-            **threaded is deprecated and included for API compatibility**
-            threaded -- If threaded=True then event dispatcher will run
-                        in a separate thread, allowing for the stream to be
-                        used in the background for another application.
-                        Defaults to True.
-
-            Event handlers and the send queue will be threaded
-            regardless of these parameters.
+        by :data:`HANDLER_THREADS`.
+
+        :param bool block: If ``False``, then event dispatcher will run
+                    in a separate thread, allowing for the stream to be
+                    used in the background for another application.
+                    Otherwise, ``process(block=True)`` blocks the current
+                    thread. Defaults to ``False``.
+        :param bool threaded: **DEPRECATED**
+                    If ``True``, then event dispatcher will run
+                    in a separate thread, allowing for the stream to be
+                    used in the background for another application.
+                    Defaults to ``True``. This does **not** mean that no
+                    threads are used at all if ``threaded=False``.
+
+        Regardless of these threading options, these threads will 
+        always exist:
+
+        - The event queue processor
+        - The send queue processor
+        - The scheduler
         """
         for name in self.plugin:
             if not self.plugin[name].post_inited:
@@ -202,15 +192,13 @@ class BaseXMPP(XMLStream):
         return XMLStream.process(self, *args, **kwargs)
 
     def register_plugin(self, plugin, pconfig={}, module=None):
-        """
-        Register and configure  a plugin for use in this stream.
+        """Register and configure  a plugin for use in this stream.
 
-        Arguments:
-            plugin  -- The name of the plugin class. Plugin names must
+        :param plugin: The name of the plugin class. Plugin names must
                        be unique.
-            pconfig -- A dictionary of configuration data for the plugin.
-                       Defaults to an empty dictionary.
-            module  -- Optional refence to the module containing the plugin
+        :param pconfig: A dictionary of configuration data for the plugin.
+                        Defaults to an empty dictionary.
+        :param module: Optional refence to the module containing the plugin
                        class if using custom plugins.
         """
         try:
@@ -251,13 +239,12 @@ class BaseXMPP(XMLStream):
             log.exception("Unable to load plugin: %s", plugin)
 
     def register_plugins(self):
-        """
-        Register and initialize all built-in plugins.
+        """Register and initialize all built-in plugins.
 
         Optionally, the list of plugins loaded may be limited to those
-        contained in self.plugin_whitelist.
+        contained in :attr:`plugin_whitelist`.
 
-        Plugin configurations stored in self.plugin_config will be used.
+        Plugin configurations stored in :attr:`plugin_config` will be used.
         """
         if self.plugin_whitelist:
             plugin_list = self.plugin_whitelist
@@ -276,9 +263,7 @@ class BaseXMPP(XMLStream):
             self.plugin[plugin].post_init()
 
     def __getitem__(self, key):
-        """
-        Return a plugin given its name, if it has been registered.
-        """
+        """Return a plugin given its name, if it has been registered."""
         if key in self.plugin:
             return self.plugin[key]
         else:
@@ -286,9 +271,7 @@ class BaseXMPP(XMLStream):
             return False
 
     def get(self, key, default):
-        """
-        Return a plugin given its name, if it has been registered.
-        """
+        """Return a plugin given its name, if it has been registered."""
         return self.plugin.get(key, default)
 
     def Message(self, *args, **kwargs):
@@ -304,16 +287,18 @@ class BaseXMPP(XMLStream):
         return Presence(self, *args, **kwargs)
 
     def make_iq(self, id=0, ifrom=None, ito=None, itype=None, iquery=None):
-        """
-        Create a new Iq stanza with a given Id and from JID.
-
-        Arguments:
-            id     -- An ideally unique ID value for this stanza thread.
-                      Defaults to 0.
-            ifrom  -- The from JID to use for this stanza.
-            ito    -- The destination JID for this stanza.
-            itype  -- The Iq's type, one of: get, set, result, or error.
-            iquery -- Optional namespace for adding a query element.
+        """Create a new Iq stanza with a given Id and from JID.
+
+        :param id: An ideally unique ID value for this stanza thread.
+                   Defaults to 0.
+        :param ifrom: The from :class:`~sleekxmpp.xmlstream.jid.JID` 
+                      to use for this stanza.
+        :param ito: The destination :class:`~sleekxmpp.xmlstream.jid.JID`
+                    for this stanza.
+        :param itype: The :class:`~sleekxmpp.stanza.iq.Iq`'s type, 
+                      one of: ``'get'``, ``'set'``, ``'result'``,
+                      or ``'error'``.
+        :param iquery: Optional namespace for adding a query element.
         """
         iq = self.Iq()
         iq['id'] = str(id)
@@ -324,17 +309,17 @@ class BaseXMPP(XMLStream):
         return iq
 
     def make_iq_get(self, queryxmlns=None, ito=None, ifrom=None, iq=None):
-        """
-        Create an Iq stanza of type 'get'.
+        """Create an :class:`~sleekxmpp.stanza.iq.Iq` stanza of type ``'get'``.
 
         Optionally, a query element may be added.
 
-        Arguments:
-            queryxmlns -- The namespace of the query to use.
-            ito        -- The destination JID for this stanza.
-            ifrom      -- The from JID to use for this stanza.
-            iq         -- Optionally use an existing stanza instead
-                          of generating a new one.
+        :param queryxmlns: The namespace of the query to use.
+        :param ito: The destination :class:`~sleekxmpp.xmlstream.jid.JID`
+                    for this stanza.
+        :param ifrom: The ``'from'`` :class:`~sleekxmpp.xmlstream.jid.JID`
+                      to use for this stanza.
+        :param iq: Optionally use an existing stanza instead
+                   of generating a new one.
         """
         if not iq:
             iq = self.Iq()
@@ -348,14 +333,16 @@ class BaseXMPP(XMLStream):
 
     def make_iq_result(self, id=None, ito=None, ifrom=None, iq=None):
         """
-        Create an Iq stanza of type 'result' with the given ID value.
-
-        Arguments:
-            id    -- An ideally unique ID value. May use self.new_id().
-            ito   -- The destination JID for this stanza.
-            ifrom -- The from JID to use for this stanza.
-            iq    -- Optionally use an existing stanza instead
-                     of generating a new one.
+        Create an :class:`~sleekxmpp.stanza.iq.Iq` stanza of type 
+        ``'result'`` with the given ID value.
+
+        :param id: An ideally unique ID value. May use :meth:`new_id()`.
+        :param ito: The destination :class:`~sleekxmpp.xmlstream.jid.JID`
+                    for this stanza.
+        :param ifrom: The ``'from'`` :class:`~sleekxmpp.xmlstream.jid.JID`
+                      to use for this stanza.
+        :param iq: Optionally use an existing stanza instead
+                   of generating a new one.
         """
         if not iq:
             iq = self.Iq()
@@ -371,17 +358,22 @@ class BaseXMPP(XMLStream):
 
     def make_iq_set(self, sub=None, ito=None, ifrom=None, iq=None):
         """
-        Create an Iq stanza of type 'set'.
+        Create an :class:`~sleekxmpp.stanza.iq.Iq` stanza of type ``'set'``.
 
         Optionally, a substanza may be given to use as the
         stanza's payload.
 
-        Arguments:
-            sub   -- A stanza or XML object to use as the Iq's payload.
-            ito   -- The destination JID for this stanza.
-            ifrom -- The from JID to use for this stanza.
-            iq    -- Optionally use an existing stanza instead
-                     of generating a new one.
+        :param sub: Either an 
+                    :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+                    stanza object or an
+                    :class:`~xml.etree.ElementTree.Element` XML object 
+                    to use as the :class:`~sleekxmpp.stanza.iq.Iq`'s payload.
+        :param ito: The destination :class:`~sleekxmpp.xmlstream.jid.JID`
+                    for this stanza.
+        :param ifrom: The ``'from'`` :class:`~sleekxmpp.xmlstream.jid.JID`
+                      to use for this stanza.
+        :param iq: Optionally use an existing stanza instead
+                   of generating a new one.
         """
         if not iq:
             iq = self.Iq()
@@ -398,19 +390,20 @@ class BaseXMPP(XMLStream):
                       condition='feature-not-implemented',
                       text=None, ito=None, ifrom=None, iq=None):
         """
-        Create an Iq stanza of type 'error'.
-
-        Arguments:
-            id        -- An ideally unique ID value. May use self.new_id().
-            type      -- The type of the error, such as 'cancel' or 'modify'.
-                         Defaults to 'cancel'.
-            condition -- The error condition.
-                         Defaults to 'feature-not-implemented'.
-            text      -- A message describing the cause of the error.
-            ito       -- The destination JID for this stanza.
-            ifrom     -- The from JID to use for this stanza.
-            iq        -- Optionally use an existing stanza instead
-                         of generating a new one.
+        Create an :class:`~sleekxmpp.stanza.iq.Iq` stanza of type ``'error'``.
+
+        :param id: An ideally unique ID value. May use :meth:`new_id()`.
+        :param type: The type of the error, such as ``'cancel'`` or 
+                     ``'modify'``. Defaults to ``'cancel'``.
+        :param condition: The error condition. Defaults to 
+                          ``'feature-not-implemented'``.
+        :param text: A message describing the cause of the error.
+        :param ito: The destination :class:`~sleekxmpp.xmlstream.jid.JID`
+                    for this stanza.
+        :param ifrom: The ``'from'`` :class:`~sleekxmpp.xmlstream.jid.JID`
+                      to use for this stanza.
+        :param iq: Optionally use an existing stanza instead
+                   of generating a new one.
         """
         if not iq:
             iq = self.Iq()
@@ -426,15 +419,16 @@ class BaseXMPP(XMLStream):
 
     def make_iq_query(self, iq=None, xmlns='', ito=None, ifrom=None):
         """
-        Create or modify an Iq stanza to use the given
-        query namespace.
-
-        Arguments:
-            iq    -- Optional Iq stanza to modify. A new
-                     stanza is created otherwise.
-            xmlns -- The query's namespace.
-            ito   -- The destination JID for this stanza.
-            ifrom -- The from JID to use for this stanza.
+        Create or modify an :class:`~sleekxmpp.stanza.iq.Iq` stanza 
+        to use the given query namespace.
+
+        :param iq: Optionally use an existing stanza instead
+                   of generating a new one.
+        :param xmlns: The query's namespace.
+        :param ito: The destination :class:`~sleekxmpp.xmlstream.jid.JID`
+                    for this stanza.
+        :param ifrom: The ``'from'`` :class:`~sleekxmpp.xmlstream.jid.JID`
+                      to use for this stanza.
         """
         if not iq:
             iq = self.Iq()
@@ -446,12 +440,10 @@ class BaseXMPP(XMLStream):
         return iq
 
     def make_query_roster(self, iq=None):
-        """
-        Create a roster query element.
+        """Create a roster query element.
 
-        Arguments:
-            iq -- Optional Iq stanza to modify. A new stanza
-                  is created otherwise.
+        :param iq: Optionally use an existing stanza instead
+                   of generating a new one.
         """
         if iq:
             iq['query'] = 'jabber:iq:roster'
@@ -460,18 +452,19 @@ class BaseXMPP(XMLStream):
     def make_message(self, mto, mbody=None, msubject=None, mtype=None,
                      mhtml=None, mfrom=None, mnick=None):
         """
-        Create and initialize a new Message stanza.
-
-        Arguments:
-            mto      -- The recipient of the message.
-            mbody    -- The main contents of the message.
-            msubject -- Optional subject for the message.
-            mtype    -- The message's type, such as 'chat' or 'groupchat'.
-            mhtml    -- Optional HTML body content.
-            mfrom    -- The sender of the message. if sending from a client,
-                        be aware that some servers require that the full JID
-                        of the sender be used.
-            mnick    -- Optional nickname of the sender.
+        Create and initialize a new 
+        :class:`~sleekxmpp.stanza.message.Message` stanza.
+
+        :param mto: The recipient of the message.
+        :param mbody: The main contents of the message.
+        :param msubject: Optional subject for the message.
+        :param mtype: The message's type, such as ``'chat'`` or
+                      ``'groupchat'``.
+        :param mhtml: Optional HTML body content in the form of a string.
+        :param mfrom: The sender of the message. if sending from a client,
+                      be aware that some servers require that the full JID
+                      of the sender be used.
+        :param mnick: Optional nickname of the sender.
         """
         message = self.Message(sto=mto, stype=mtype, sfrom=mfrom)
         message['body'] = mbody
@@ -485,16 +478,16 @@ class BaseXMPP(XMLStream):
     def make_presence(self, pshow=None, pstatus=None, ppriority=None,
                       pto=None, ptype=None, pfrom=None, pnick=None):
         """
-        Create and initialize a new Presence stanza.
-
-        Arguments:
-            pshow     -- The presence's show value.
-            pstatus   -- The presence's status message.
-            ppriority -- This connections' priority.
-            pto       -- The recipient of a directed presence.
-            ptype     -- The type of presence, such as 'subscribe'.
-            pfrom     -- The sender of the presence.
-            pnick     -- Optional nickname of the presence's sender.
+        Create and initialize a new 
+        :class:`~sleekxmpp.stanza.presence.Presence` stanza.
+
+        :param pshow: The presence's show value.
+        :param pstatus: The presence's status message.
+        :param ppriority: This connection's priority.
+        :param pto: The recipient of a directed presence.
+        :param ptype: The type of presence, such as ``'subscribe'``.
+        :param pfrom: The sender of the presence.
+        :param pnick: Optional nickname of the presence's sender.
         """
         presence = self.Presence(stype=ptype, sfrom=pfrom, sto=pto)
         if pshow is not None:
@@ -509,18 +502,19 @@ class BaseXMPP(XMLStream):
     def send_message(self, mto, mbody, msubject=None, mtype=None,
                      mhtml=None, mfrom=None, mnick=None):
         """
-        Create, initialize, and send a Message stanza.
-
-        Arguments:
-            mto      -- The recipient of the message.
-            mbody    -- The main contents of the message.
-            msubject -- Optional subject for the message.
-            mtype    -- The message's type, such as 'chat' or 'groupchat'.
-            mhtml    -- Optional HTML body content.
-            mfrom    -- The sender of the message. if sending from a client,
-                        be aware that some servers require that the full JID
-                        of the sender be used.
-            mnick    -- Optional nickname of the sender.
+        Create, initialize, and send a new 
+        :class:`~sleekxmpp.stanza.message.Message` stanza.
+
+        :param mto: The recipient of the message.
+        :param mbody: The main contents of the message.
+        :param msubject: Optional subject for the message.
+        :param mtype: The message's type, such as ``'chat'`` or
+                      ``'groupchat'``.
+        :param mhtml: Optional HTML body content in the form of a string.
+        :param mfrom: The sender of the message. if sending from a client,
+                      be aware that some servers require that the full JID
+                      of the sender be used.
+        :param mnick: Optional nickname of the sender.
         """
         self.make_message(mto, mbody, msubject, mtype,
                           mhtml, mfrom, mnick).send()
@@ -528,16 +522,16 @@ class BaseXMPP(XMLStream):
     def send_presence(self, pshow=None, pstatus=None, ppriority=None,
                       pto=None, pfrom=None, ptype=None, pnick=None):
         """
-        Create, initialize, and send a Presence stanza.
-
-        Arguments:
-            pshow     -- The presence's show value.
-            pstatus   -- The presence's status message.
-            ppriority -- This connections' priority.
-            pto       -- The recipient of a directed presence.
-            ptype     -- The type of presence, such as 'subscribe'.
-            pfrom     -- The sender of the presence.
-            pnick     -- Optional nickname of the presence's sender.
+        Create, initialize, and send a new 
+        :class:`~sleekxmpp.stanza.presence.Presence` stanza.
+
+        :param pshow: The presence's show value.
+        :param pstatus: The presence's status message.
+        :param ppriority: This connection's priority.
+        :param pto: The recipient of a directed presence.
+        :param ptype: The type of presence, such as ``'subscribe'``.
+        :param pfrom: The sender of the presence.
+        :param pnick: Optional nickname of the presence's sender.
         """
         # Python2.6 chokes on Unicode strings for dict keys.
         args = {str('pto'): pto,
@@ -555,13 +549,14 @@ class BaseXMPP(XMLStream):
     def send_presence_subscription(self, pto, pfrom=None,
                                    ptype='subscribe', pnick=None):
         """
-        Create, initialize, and send a Presence stanza of type 'subscribe'.
+        Create, initialize, and send a new 
+        :class:`~sleekxmpp.stanza.presence.Presence` stanza of
+        type ``'subscribe'``.
 
-        Arguments:
-            pto   -- The recipient of a directed presence.
-            pfrom -- The sender of the presence.
-            ptype -- The type of presence. Defaults to 'subscribe'.
-            pnick -- Nickname of the presence's sender.
+        :param pto: The recipient of a directed presence.
+        :param pfrom: The sender of the presence.
+        :param ptype: The type of presence, such as ``'subscribe'``.
+        :param pnick: Optional nickname of the presence's sender.
         """
         presence = self.makePresence(ptype=ptype,
                                      pfrom=pfrom,
@@ -574,9 +569,7 @@ class BaseXMPP(XMLStream):
 
     @property
     def jid(self):
-        """
-        Attribute accessor for bare jid
-        """
+        """Attribute accessor for bare jid"""
         log.warning("jid property deprecated. Use boundjid.bare")
         return self.boundjid.bare
 
@@ -587,9 +580,7 @@ class BaseXMPP(XMLStream):
 
     @property
     def fulljid(self):
-        """
-        Attribute accessor for full jid
-        """
+        """Attribute accessor for full jid"""
         log.warning("fulljid property deprecated. Use boundjid.full")
         return self.boundjid.full
 
@@ -600,9 +591,7 @@ class BaseXMPP(XMLStream):
 
     @property
     def resource(self):
-        """
-        Attribute accessor for jid resource
-        """
+        """Attribute accessor for jid resource"""
         log.warning("resource property deprecated. Use boundjid.resource")
         return self.boundjid.resource
 
@@ -613,9 +602,7 @@ class BaseXMPP(XMLStream):
 
     @property
     def username(self):
-        """
-        Attribute accessor for jid usernode
-        """
+        """Attribute accessor for jid usernode"""
         log.warning("username property deprecated. Use boundjid.user")
         return self.boundjid.user
 
@@ -626,9 +613,7 @@ class BaseXMPP(XMLStream):
 
     @property
     def server(self):
-        """
-        Attribute accessor for jid host
-        """
+        """Attribute accessor for jid host"""
         log.warning("server property deprecated. Use boundjid.host")
         return self.boundjid.server
 
@@ -639,42 +624,28 @@ class BaseXMPP(XMLStream):
 
     @property
     def auto_authorize(self):
-        """
-        Auto accept or deny subscription requests.
+        """Auto accept or deny subscription requests.
 
-        If True, auto accept subscription requests.
-        If False, auto deny subscription requests.
-        If None, don't automatically respond.
+        If ``True``, auto accept subscription requests.
+        If ``False``, auto deny subscription requests.
+        If ``None``, don't automatically respond.
         """
         return self.roster.auto_authorize
 
     @auto_authorize.setter
     def auto_authorize(self, value):
-        """
-        Auto accept or deny subscription requests.
-
-        If True, auto accept subscription requests.
-        If False, auto deny subscription requests.
-        If None, don't automatically respond.
-        """
         self.roster.auto_authorize = value
 
     @property
     def auto_subscribe(self):
-        """
-        Auto send requests for mutual subscriptions.
+        """Auto send requests for mutual subscriptions.
 
-        If True, auto send mutual subscription requests.
+        If ``True``, auto send mutual subscription requests.
         """
         return self.roster.auto_subscribe
 
     @auto_subscribe.setter
     def auto_subscribe(self, value):
-        """
-        Auto send requests for mutual subscriptions.
-
-        If True, auto send mutual subscription requests.
-        """
         self.roster.auto_subscribe = value
 
     def set_jid(self, jid):
@@ -713,17 +684,16 @@ class BaseXMPP(XMLStream):
         self.roster[pto][pfrom].handle_unavailable(presence)
 
     def _handle_new_subscription(self, stanza):
-        """
-        Attempt to automatically handle subscription requests.
+        """Attempt to automatically handle subscription requests.
 
         Subscriptions will be approved if the request is from
-        a whitelisted JID, of self.auto_authorize is True. They
-        will be rejected if self.auto_authorize is False. Setting
-        self.auto_authorize to None will disable automatic
+        a whitelisted JID, of :attr:`auto_authorize` is True. They
+        will be rejected if :attr:`auto_authorize` is False. Setting
+        :attr:`auto_authorize` to ``None`` will disable automatic
         subscription handling (except for whitelisted JIDs).
 
         If a subscription is accepted, a request for a mutual
-        subscription will be sent if self.auto_subscribe is True.
+        subscription will be sent if :attr:`auto_subscribe` is ``True``.
         """
         roster = self.roster[stanza['to'].bare]
         item = self.roster[stanza['to'].bare][stanza['from'].bare]
@@ -762,8 +732,7 @@ class BaseXMPP(XMLStream):
         self.roster[pto][pfrom].handle_unsubscribed(presence)
 
     def _handle_presence(self, presence):
-        """
-        Process incoming presence stanzas.
+        """Process incoming presence stanzas.
 
         Update the roster with presence information.
         """
@@ -779,14 +748,11 @@ class BaseXMPP(XMLStream):
             return
 
     def exception(self, exception):
-        """
-        Process any uncaught exceptions, notably IqError and
-        IqTimeout exceptions.
-
-        Overrides XMLStream.exception.
+        """Process any uncaught exceptions, notably 
+        :class:`~sleekxmpp.exceptions.IqError` and
+        :class:`~sleekxmpp.exceptions.IqTimeout` exceptions.
 
-        Arguments:
-            exception -- An unhandled exception object.
+        :param exception: An unhandled :class:`Exception` object.
         """
         if isinstance(exception, IqError):
             iq = exception.iq
diff --git a/sleekxmpp/exceptions.py b/sleekxmpp/exceptions.py
index 61d24f6b..6bac1e40 100644
--- a/sleekxmpp/exceptions.py
+++ b/sleekxmpp/exceptions.py
@@ -1,9 +1,12 @@
+# -*- coding: utf-8 -*-
 """
-    SleekXMPP: The Sleek XMPP Library
-    Copyright (C) 2010  Nathanael C. Fritz
-    This file is part of SleekXMPP.
+    sleekxmpp.exceptions
+    ~~~~~~~~~~~~~~~~~~~~
 
-    See the file LICENSE for copying permission.
+    Part of SleekXMPP: The Sleek XMPP Library
+
+    :copyright: (c) 2011 Nathanael C. Fritz
+    :license: MIT, see LICENSE for more details
 """
 
 
@@ -13,37 +16,35 @@ class XMPPError(Exception):
     A generic exception that may be raised while processing an XMPP stanza
     to indicate that an error response stanza should be sent.
 
-    The exception method for stanza objects extending RootStanza will create
-    an error stanza and initialize any additional substanzas using the
-    extension information included in the exception.
+    The exception method for stanza objects extending
+    :class:`~sleekxmpp.stanza.rootstanza.RootStanza` will create an error
+    stanza and initialize any additional substanzas using the extension
+    information included in the exception.
 
     Meant for use in SleekXMPP plugins and applications using SleekXMPP.
+
+    Extension information can be included to add additional XML elements
+    to the generated error stanza.
+
+    :param condition: The XMPP defined error condition.
+                      Defaults to ``'undefined-condition'``.
+    :param text: Human readable text describing the error.
+    :param etype: The XMPP error type, such as ``'cancel'`` or ``'modify'``.
+                  Defaults to ``'cancel'``.
+    :param extension: Tag name of the extension's XML content.
+    :param extension_ns: XML namespace of the extensions' XML content.
+    :param extension_args: Content and attributes for the extension
+                           element. Same as the additional arguments to
+                           the :class:`~xml.etree.ElementTree.Element`
+                           constructor.
+    :param clear: Indicates if the stanza's contents should be
+                  removed before replying with an error.
+                  Defaults to ``True``.
     """
 
     def __init__(self, condition='undefined-condition', text=None,
                 etype='cancel', extension=None, extension_ns=None,
                 extension_args=None, clear=True):
-        """
-        Create a new XMPPError exception.
-
-        Extension information can be included to add additional XML elements
-        to the generated error stanza.
-
-        Arguments:
-            condition      -- The XMPP defined error condition.
-                              Defaults to 'undefined-condition'.
-            text           -- Human readable text describing the error.
-            etype          -- The XMPP error type, such as cancel or modify.
-                              Defaults to 'cancel'.
-            extension      -- Tag name of the extension's XML content.
-            extension_ns   -- XML namespace of the extensions' XML content.
-            extension_args -- Content and attributes for the extension
-                              element. Same as the additional arguments to
-                              the ET.Element constructor.
-            clear          -- Indicates if the stanza's contents should be
-                              removed before replying with an error.
-                              Defaults to True.
-        """
         if extension_args is None:
             extension_args = {}
 
@@ -68,6 +69,8 @@ class IqTimeout(XMPPError):
                 condition='remote-server-timeout',
                 etype='cancel')
 
+        #: The :class:`~sleekxmpp.stanza.iq.Iq` stanza whose response 
+        #: did not arrive before the timeout expired.
         self.iq = iq
 
 class IqError(XMPPError):
@@ -83,4 +86,5 @@ class IqError(XMPPError):
                 text=iq['error']['text'],
                 etype=iq['error']['type'])
 
+        #: The :class:`~sleekxmpp.stanza.iq.Iq` error result stanza.
         self.iq = iq