Update api docs for handlers and matchers

1 files changed, 38 insertions, 44 deletions

diff --git a/sleekxmpp/xmlstream/handler/callback.py b/sleekxmpp/xmlstream/handler/callback.py
index 7fadab43..37f53335 100644
--- a/sleekxmpp/xmlstream/handler/callback.py
+++ b/sleekxmpp/xmlstream/handler/callback.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.handler.callback
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    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.handler.base import BaseHandler
@@ -18,48 +21,42 @@ class Callback(BaseHandler):
     The handler may execute the callback either during stream
     processing or during the main event loop.
 
-    Callback functions are all executed in the same thread, so be
-    aware if you are executing functions that will block for extended
-    periods of time. Typically, you should signal your own events using the
-    SleekXMPP object's event() method to pass the stanza off to a threaded
-    event handler for further processing.
-
-    Methods:
-        prerun -- Overrides BaseHandler.prerun
-        run    -- Overrides BaseHandler.run
+    Callback functions are all executed in the same thread, so be aware if
+    you are executing functions that will block for extended periods of
+    time. Typically, you should signal your own events using the SleekXMPP
+    object's :meth:`~sleekxmpp.xmlstream.xmlstream.XMLStream.event()`
+    method to pass the stanza off to a threaded event handler for further
+    processing.
+
+
+    :param string name: The name of the handler.
+    :param matcher: A :class:`~sleekxmpp.xmlstream.matcher.base.MatcherBase`
+                    derived object for matching stanza objects.
+    :param pointer: The function to execute during callback.
+    :param bool thread: **DEPRECATED.** Remains only for 
+                        backwards compatibility.
+    :param bool once: Indicates if the handler should be used only
+                      once. Defaults to False.
+    :param bool instream: Indicates if the callback should be executed
+                          during stream processing instead of in the
+                          main event loop.
+    :param stream: The :class:`~sleekxmpp.xmlstream.xmlstream.XMLStream`
+                   instance this handler should monitor.
     """
 
     def __init__(self, name, matcher, pointer, thread=False,
                  once=False, instream=False, stream=None):
-        """
-        Create a new callback handler.
-
-        Arguments:
-            name     -- The name of the handler.
-            matcher  -- A matcher object for matching stanza objects.
-            pointer  -- The function to execute during callback.
-            thread   -- DEPRECATED. Remains only for backwards compatibility.
-            once     -- Indicates if the handler should be used only
-                        once. Defaults to False.
-            instream -- Indicates if the callback should be executed
-                        during stream processing instead of in the
-                        main event loop.
-            stream   -- The XMLStream instance this handler should monitor.
-        """
         BaseHandler.__init__(self, name, matcher, stream)
         self._pointer = pointer
         self._once = once
         self._instream = instream
 
     def prerun(self, payload):
-        """
-        Execute the callback during stream processing, if
-        the callback was created with instream=True.
-
-        Overrides BaseHandler.prerun
+        """Execute the callback during stream processing, if
+        the callback was created with ``instream=True``.
 
-        Arguments:
-            payload -- The matched stanza object.
+        :param payload: The matched
+            :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object.
         """
         if self._once:
             self._destroy = True
@@ -67,16 +64,13 @@ class Callback(BaseHandler):
             self.run(payload, True)
 
     def run(self, payload, instream=False):
-        """
-        Execute the callback function with the matched stanza payload.
-
-        Overrides BaseHandler.run
+        """Execute the callback function with the matched stanza payload.
 
-        Arguments:
-            payload  -- The matched stanza object.
-            instream -- Force the handler to execute during
-                        stream processing. Used only by prerun.
-                        Defaults to False.
+        :param payload: The matched
+            :class:`~sleekxmpp.xmlstream.stanzabase.ElementBase` object.
+        :param bool instream: Force the handler to execute during stream
+                              processing. This should only be used by
+                              :meth:`prerun()`. Defaults to ``False``.
         """
         if not self._instream or instream:
             self._pointer(payload)