From e8e4b0bb4c9b98f64934cebcc3e4faff63b1f562 Mon Sep 17 00:00:00 2001
From: mathieui <mathieui@mathieui.net>
Date: Wed, 9 Nov 2011 18:38:56 +0100
Subject: Plugin docstrings

---
 src/events.py |  5 ++---
 src/plugin.py | 27 ++++++++++++++++++++++++---
 2 files changed, 26 insertions(+), 6 deletions(-)

diff --git a/src/events.py b/src/events.py
index 22d60ddf..cd45448f 100644
--- a/src/events.py
+++ b/src/events.py
@@ -20,7 +20,6 @@ class EventHandler(object):
     """
     def __init__(self):
         self.events = {
-            # when you are highlighted in a muc tab
             'highlight': [],
             'muc_say': [],
             'conversation_say': [],
@@ -35,7 +34,7 @@ class EventHandler(object):
         Add a callback to a given event.
         Note that if that event name doesn’t exist, it just returns False.
         If it was successfully added, it returns True
-        position: 0 means insert a the beginning, -1 means end
+        position: 0 means insert at the beginning, -1 means end
         """
         if name not in self.events:
             return False
@@ -49,7 +48,7 @@ class EventHandler(object):
 
     def trigger(self, name, *args, **kwargs):
         """
-        Call all the callbacks associated to the given event name
+        Call all the callbacks associated to the given event name.
         """
         callbacks = self.events[name]
         for callback in callbacks:
diff --git a/src/plugin.py b/src/plugin.py
index c87ba2f1..40f96871 100644
--- a/src/plugin.py
+++ b/src/plugin.py
@@ -50,9 +50,7 @@ class SafetyMetaclass(type):
 
 class BasePlugin(object, metaclass=SafetyMetaclass):
     """
-    Class that all plugins derive from.  Any methods beginning with command_
-    are interpreted as a command and beginning with on_ are interpreted as
-    event handlers
+    Class that all plugins derive from.
     """
 
     def __init__(self, plugin_manager, core, plugins_conf_dir):
@@ -65,22 +63,45 @@ class BasePlugin(object, metaclass=SafetyMetaclass):
         self.init()
 
     def init(self):
+        """
+        Method called at the creation of the plugin.
+        Do not overwrite __init__ and use this instead.
+        """
         pass
 
     def cleanup(self):
+        """
+        Called when the plugin is unloaded.
+        Overwrite this if you want to erase or save things before the plugin is disabled.
+        """
         pass
 
     def unload(self):
         self.cleanup()
 
     def add_command(self, name, handler, help, completion=None):
+        """
+        Add a global command.
+        You cannot overwrite the existing commands.
+        """
         return self.plugin_manager.add_command(self.__module__, name, handler, help, completion)
 
     def del_command(self, name):
+        """
+        Remove a global command.
+        This only works if the command was added by the plugin
+        """
         return self.plugin_manager.del_command(self.__module__, name)
 
     def add_event_handler(self, event_name, handler, position=0):
+        """
+        Add an event handler to the event event_name.
+        An optional position in the event handler list can be provided.
+        """
         return self.plugin_manager.add_event_handler(self.__module__, event_name, handler, position)
 
     def del_event_handler(self, event_name, handler):
+        """
+        Remove 'handler' from the event list for 'event_name'.
+        """
         return self.plugin_manager.del_event_handler(self.__module__, event_name, handler)
-- 
cgit v1.2.3