Update some docs.

4 files changed, 74 insertions, 21 deletions

diff --git a/sleekxmpp/plugins/xep_0030/disco.py b/sleekxmpp/plugins/xep_0030/disco.py
index c323ba7c..c272929e 100644
--- a/sleekxmpp/plugins/xep_0030/disco.py
+++ b/sleekxmpp/plugins/xep_0030/disco.py
@@ -26,15 +26,23 @@ class xep_0030(base_plugin):
     """
     XEP-0030: Service Discovery
 
+    Service discovery in XMPP allows entities to discover information about
+    other agents in the network, such as the feature sets supported by a
+    client, or signposts to other, related entities.
+
+    Also see <http://www.xmpp.org/extensions/xep-0030.html>.
+
     Stream Handlers:
-        Disco Info  --
-        Disco Items --
+        Disco Info  -- Any Iq stanze that includes a query with the
+                       namespace http://jabber.org/protocol/disco#info.
+        Disco Items -- Any Iq stanze that includes a query with the
+                       namespace http://jabber.org/protocol/disco#items.
 
     Events:
-        disco_info         --
-        disco_items        --
-        disco_info_query   --
-        disco_items_query  --
+        disco_info         -- Received a disco#info Iq query result.
+        disco_items        -- Received a disco#items Iq query result.
+        disco_info_query   -- Received a disco#info Iq query request.
+        disco_items_query  -- Received a disco#items Iq query request.
 
     Methods:
         set_node_handler --
@@ -79,14 +87,45 @@ class xep_0030(base_plugin):
                                  'jid': {},
                                  'node': {}}
 
-
     def set_node_handler(self, htype, jid=None, node=None, handler=None):
         """
+        Add a node handler for the given hierarchy level and
+        handler type.
+
+        Node handlers are ordered in a hierarchy where the
+        most specific handler is executed. Thus, a fallback,
+        global handler can be used for the majority of cases
+        with a few node specific handler that override the
+        global behavior.
+
+        Node handler hierarchy:
+            JID   | Node  | Level
+            ---------------------
+            None  | None  | Global
+            Given | None  | All nodes for the JID
+            None  | Given | Node on self.xmpp.boundjid
+            Given | Given | A single node
+
+        Handler types:
+            get_info
+            get_items
+            set_identities
+            set_features
+            set_items
+            del_info
+            del_items
+            del_identity
+            del_feature
+            del_item
+            add_identity
+            add_feature
+            add_item
+ 
         Arguments:
-            htype
-            jid
-            node
-            handler
+            htype   -- The operation provided by the handler.
+            jid     --
+            node    --
+            handler --
         """
         if htype not in self._disco_ops:
             return
@@ -102,10 +141,24 @@ class xep_0030(base_plugin):
 
     def del_node_handler(self, htype, jid, node):
         """
+        Remove a handler type for a JID and node combination.
+
+        The next handler in the hierarchy will be used if one
+        exists. If removing the global handler, make sure that
+        other handlers exist to process existing nodes.
+
+        Node handler hierarchy:
+            JID   | Node  | Level
+            ---------------------
+            None  | None  | Global
+            Given | None  | All nodes for the JID
+            None  | Given | Node on self.xmpp.boundjid
+            Given | Given | A single node
+
         Arguments:
-            htype
-            jid
-            node
+            htype -- The type of handler to remove.
+            jid   -- The JID from which to remove the handler.
+            node  -- The node from which to remove the handler.
         """
         self.set_node_handler(htype, jid, node, None)
 
@@ -218,7 +271,7 @@ class xep_0030(base_plugin):
             htype -- The handler type to execute.
             jid   -- The JID requested.
             node  -- The node requested.
-            dat   -- Optional, custom data to pass to the handler.
+            data  -- Optional, custom data to pass to the handler.
         """
         if jid is None:
             jid = self.xmpp.boundjid.full
@@ -311,4 +364,3 @@ class xep_0030(base_plugin):
                           "Using default disco#info feature.")
                 info.add_feature(info.namespace)
         return info
-
diff --git a/sleekxmpp/plugins/xep_0030/stanza/disco.py b/sleekxmpp/plugins/xep_0030/stanza/disco.py
deleted file mode 100644
index e69de29b..00000000
--- a/sleekxmpp/plugins/xep_0030/stanza/disco.py
+++ /dev/null
diff --git a/sleekxmpp/plugins/xep_0030/stanza/items.py b/sleekxmpp/plugins/xep_0030/stanza/items.py
index 319e666f..a1fb819c 100644
--- a/sleekxmpp/plugins/xep_0030/stanza/items.py
+++ b/sleekxmpp/plugins/xep_0030/stanza/items.py
@@ -12,8 +12,6 @@ from sleekxmpp.xmlstream import ElementBase, ET
 class DiscoItems(ElementBase):
 
     """
-             
-
     Example disco#items stanzas:
         <iq type="get">
           <query xmlns="http://jabber.org/protocol/disco#items" />
@@ -74,7 +72,7 @@ class DiscoItems(ElementBase):
 
         Arguments:
             jid  -- The JID for the item.
-            node -- Optional additional information to reference 
+            node -- Optional additional information to reference
                     non-addressable items.
             name -- Optional human readable name for the item.
         """
diff --git a/sleekxmpp/plugins/xep_0030/static.py b/sleekxmpp/plugins/xep_0030/static.py
index f3693228..e2d03315 100644
--- a/sleekxmpp/plugins/xep_0030/static.py
+++ b/sleekxmpp/plugins/xep_0030/static.py
@@ -35,6 +35,11 @@ class StaticDisco(object):
 
     def __init__(self, xmpp):
         """
+        Create a static disco interface. Sets of disco#info and
+        disco#items are maintained for every given JID and node
+        combination. These stanzas are used to store disco
+        information in memory without any additional processing.
+
         Arguments:
             xmpp -- The main SleekXMPP object.
         """
@@ -101,7 +106,6 @@ class StaticDisco(object):
                 data.get('name', None),
                 data.get('lang', None))
 
-
     def add_feature(self, jid, node, data=None):
         self.add_node(jid, node)
         self.nodes[(jid, node)]['info'].add_feature(data.get('feature', ''))
@@ -124,4 +128,3 @@ class StaticDisco(object):
     def del_item(self, jid, node, data=None):
         if (jid, node) in self.nodes:
             self.nodes[(jid, node)]['items'].del_item(**data)
-