Update api docs for handlers and matchers

4 files changed, 58 insertions, 61 deletions

diff --git a/sleekxmpp/xmlstream/matcher/base.py b/sleekxmpp/xmlstream/matcher/base.py
index 701ab32f..83c26688 100644
--- a/sleekxmpp/xmlstream/matcher/base.py
+++ b/sleekxmpp/xmlstream/matcher/base.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.xmlstream.matcher.base
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    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,21 +16,15 @@ class MatcherBase(object):
     Base class for stanza matchers. Stanza matchers are used to pick
     stanzas out of the XML stream and pass them to the appropriate
     stream handlers.
+
+    :param criteria: Object to compare some aspect of a stanza against.
     """
 
     def __init__(self, criteria):
-        """
-        Create a new stanza matcher.
-
-        Arguments:
-            criteria -- Object to compare some aspect of a stanza
-                        against.
-        """
         self._criteria = criteria
 
     def match(self, xml):
-        """
-        Check if a stanza matches the stored criteria.
+        """Check if a stanza matches the stored criteria.
 
         Meant to be overridden.
         """
diff --git a/sleekxmpp/xmlstream/matcher/id.py b/sleekxmpp/xmlstream/matcher/id.py
index 0c8ce2d8..11ab70bb 100644
--- a/sleekxmpp/xmlstream/matcher/id.py
+++ b/sleekxmpp/xmlstream/matcher/id.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.xmlstream.matcher.id
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    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
 """
 
 from sleekxmpp.xmlstream.matcher.base import MatcherBase
@@ -14,19 +17,13 @@ class MatcherId(MatcherBase):
     """
     The ID matcher selects stanzas that have the same stanza 'id'
     interface value as the desired ID.
-
-    Methods:
-        match -- Overrides MatcherBase.match.
     """
 
     def match(self, xml):
-        """
-        Compare the given stanza's 'id' attribute to the stored
-        id value.
-
-        Overrides MatcherBase.match.
+        """Compare the given stanza's ``'id'`` attribute to the stored
+        ``id`` value.
 
-        Arguments:
-            xml -- The stanza to compare against.
+        :param xml: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+                    stanza to compare against.
         """
         return xml['id'] == self._criteria
diff --git a/sleekxmpp/xmlstream/matcher/stanzapath.py b/sleekxmpp/xmlstream/matcher/stanzapath.py
index f8ff283d..61c5332c 100644
--- a/sleekxmpp/xmlstream/matcher/stanzapath.py
+++ b/sleekxmpp/xmlstream/matcher/stanzapath.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.xmlstream.matcher.stanzapath
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    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
 """
 
 from sleekxmpp.xmlstream.matcher.base import MatcherBase
@@ -15,24 +18,17 @@ class StanzaPath(MatcherBase):
     The StanzaPath matcher selects stanzas that match a given "stanza path",
     which is similar to a normal XPath except that it uses the interfaces and
     plugins of the stanza instead of the actual, underlying XML.
-
-    In most cases, the stanza path and XPath should be identical, but be
-    aware that differences may occur.
-
-    Methods:
-        match -- Overrides MatcherBase.match.
     """
 
     def match(self, stanza):
         """
         Compare a stanza against a "stanza path". A stanza path is similar to
         an XPath expression, but uses the stanza's interfaces and plugins
-        instead of the underlying XML. For most cases, the stanza path and
-        XPath should be identical, but be aware that differences may occur.
-
-        Overrides MatcherBase.match.
+        instead of the underlying XML. See the documentation for the stanza
+        :meth:`~sleekxmpp.xmlstream.stanzabase.ElementBase.match()` method
+        for more information.
 
-        Arguments:
-            stanza -- The stanza object to compare against.
+        :param stanza: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+                       stanza to compare against.
         """
         return stanza.match(self._criteria)
diff --git a/sleekxmpp/xmlstream/matcher/xpath.py b/sleekxmpp/xmlstream/matcher/xpath.py
index 669c9f16..b6af0609 100644
--- a/sleekxmpp/xmlstream/matcher/xpath.py
+++ b/sleekxmpp/xmlstream/matcher/xpath.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.xmlstream.matcher.xpath
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    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
 """
 
 from sleekxmpp.xmlstream.stanzabase import ET
@@ -22,30 +25,34 @@ class MatchXPath(MatcherBase):
     The XPath matcher selects stanzas whose XML contents matches a given
     XPath expression.
 
-    Note that using this matcher may not produce expected behavior when using
-    attribute selectors. For Python 2.6 and 3.1, the ElementTree find method
-    does not support the use of attribute selectors. If you need to support
-    Python 2.6 or 3.1, it might be more useful to use a StanzaPath matcher.
+    .. warning::
 
-    If the value of IGNORE_NS is set to true, then XPath expressions will
-    be matched without using namespaces.
+        Using this matcher may not produce expected behavior when using
+        attribute selectors. For Python 2.6 and 3.1, the ElementTree
+        :meth:`~xml.etree.ElementTree.Element.find()` method does
+        not support the use of attribute selectors. If you need to
+        support Python 2.6 or 3.1, it might be more useful to use a
+        :class:`~sleekxmpp.xmlstream.matcher.stanzapath.StanzaPath` matcher.
 
-    Methods:
-        match -- Overrides MatcherBase.match.
+    If the value of :data:`IGNORE_NS` is set to ``True``, then XPath
+    expressions will be matched without using namespaces.
     """
 
     def match(self, xml):
         """
         Compare a stanza's XML contents to an XPath expression.
 
-        If the value of IGNORE_NS is set to true, then XPath expressions
-        will be matched without using namespaces.
+        If the value of :data:`IGNORE_NS` is set to ``True``, then XPath
+        expressions will be matched without using namespaces.
+
+        .. warning::
 
-        Note that in Python 2.6 and 3.1 the ElementTree find method does
-        not support attribute selectors in the XPath expression.
+            In Python 2.6 and 3.1 the ElementTree
+            :meth:`~xml.etree.ElementTree.Element.find()` method does not
+            support attribute selectors in the XPath expression.
 
-        Arguments:
-            xml -- The stanza object to compare against.
+        :param xml: The :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase`
+                    stanza to compare against.
         """
         if hasattr(xml, 'xml'):
             xml = xml.xml