From 0234d8ce63e18f1faa9d77f09ce2165d1c36b206 Mon Sep 17 00:00:00 2001
From: Ben Kurtovic <ben.kurtovic@verizon.net>
Date: Fri, 6 Apr 2012 16:22:47 -0400
Subject: [PATCH] Docstring updates; watcher's process() now takes Bot object

---
 earwigbot/bot.py         |  9 +++++++--
 earwigbot/irc/watcher.py | 13 +++++++------
 2 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/earwigbot/bot.py b/earwigbot/bot.py
index a005ac6..ac2c566 100644
--- a/earwigbot/bot.py
+++ b/earwigbot/bot.py
@@ -34,8 +34,7 @@ __all__ = ["Bot"]
 class Bot(object):
     """
     The Bot class is the core of EarwigBot, essentially responsible for
-    starting the various bot components and making sure they are all happy. An
-    explanation of the different components follows:
+    starting the various bot components and making sure they are all happy.
 
     EarwigBot has three components that can run independently of each other: an
     IRC front-end, an IRC watcher, and a wiki scheduler.
@@ -45,6 +44,12 @@ class Bot(object):
       edits. Users cannot interact with this part of the bot.
     * The wiki scheduler runs wiki-editing bot tasks in separate threads at
       user-defined times through a cron-like interface.
+ 
+    The Bot() object is accessable from within commands and tasks as self.bot.
+    This is the primary way to access data from other components of the bot.
+    For example, our BotConfig object is accessable from bot.config, tasks
+    can be started with bot.tasks.start(), and sites can be loaded from the
+    wiki toolset with bot.wiki.get_site().
     """
 
     def __init__(self, root_dir):
diff --git a/earwigbot/irc/watcher.py b/earwigbot/irc/watcher.py
index 572a3aa..f306802 100644
--- a/earwigbot/irc/watcher.py
+++ b/earwigbot/irc/watcher.py
@@ -33,8 +33,8 @@ class Watcher(IRCConnection):
     The IRC watcher runs on a wiki recent-changes server and listens for
     edits. Users cannot interact with this part of the bot. When an event
     occurs, we run it through some rules stored in our config, which can result
-    in wiki bot tasks being started (located in tasks/) or messages being sent
-    to channels on the IRC frontend.
+    in wiki bot tasks being started or messages being sent to channels on the
+    IRC frontend.
     """
 
     def __init__(self, bot):
@@ -77,8 +77,9 @@ class Watcher(IRCConnection):
     def _prepare_process_hook(self):
         """Create our RC event process hook from information in config.
 
-        This will get put in the function self._process_hook, which takes an RC
-        object and returns a list of frontend channels to report this event to.
+        This will get put in the function self._process_hook, which takes the
+        Bot object and an RC object and returns a list of frontend channels to
+        report this event to.
         """
         # Set a default RC process hook that does nothing:
         self._process_hook = lambda rc: ()
@@ -98,7 +99,7 @@ class Watcher(IRCConnection):
         try:
             self._process_hook = module.process
         except AttributeError:
-            e = "RC event rules compiled correctly, but no process(rc) function was found"
+            e = "RC event rules compiled correctly, but no process(bot, rc) function was found"
             self.logger.error(e)
             return
 
@@ -110,7 +111,7 @@ class Watcher(IRCConnection):
         self._prepare_process_hook() from information in the "rules" section of
         our config.
         """
-        chans = self._process_hook(rc)
+        chans = self._process_hook(self.bot, rc)
         with self.bot.component_lock:
             frontend = self.bot.frontend
             if chans and frontend and not frontend.is_stopped():