Merge lp:~cjwatson/storm/docstring-event into lp:storm

[Colin Watson]

Add docstrings for storm.event.EventSystem.

[Ioana Lasc (ilasc)]

review: Approve

=== modified file 'storm/event.py'
--- storm/event.py	2019-06-05 11:41:07 +0000
+++ storm/event.py	2020-05-29 22:16:29 +0000
@@ -29,12 +29,35 @@
 
 
 class EventSystem(object):
+    """A system for managing hooks that are called when events are emitted.
+
+    Hooks are callables that take the event system C{owner} as their first
+    argument, followed by the arguments passed when emitting the event,
+    followed by any additional C{data} arguments given when registering the
+    hook.
+
+    Hooks registered for a given event C{name} are stored without ordering:
+    no particular call order may be assumed when an event is emitted.
+    """
 
     def __init__(self, owner):
+        """
+        @param owner: The object that owns this event system.  It is passed
+            as the first argument to each hook function.
+        """
         self._owner_ref = weakref.ref(owner)
         self._hooks = {}
 
     def hook(self, name, callback, *data):
+        """Register a hook.
+
+        @param name: The name of the event for which this hook should be
+            called.
+        @param callback: A callable which should be called when the event is
+            emitted.
+        @param data: Additional arguments to pass to the callable, after the
+            C{owner} and any arguments passed when emitting the event.
+        """
         callbacks = self._hooks.get(name)
         if callbacks is None:
             self._hooks.setdefault(name, set()).add((callback, data))
@@ -42,11 +65,27 @@
             callbacks.add((callback, data))
 
     def unhook(self, name, callback, *data):
+        """Unregister a hook.
+
+        This ignores attempts to unregister hooks that were not already
+        registered.
+
+        @param name: The name of the event for which this hook should no
+            longer be called.
+        @param callback: The callable to unregister.
+        @param data: Additional arguments that were passed when registering
+            the callable.
+        """
         callbacks = self._hooks.get(name)
         if callbacks is not None:
             callbacks.discard((callback, data))
 
     def emit(self, name, *args):
+        """Emit an event, calling any registered hooks.
+
+        @param name: The name of the event.
+        @param args: Additional arguments to pass to hooks.
+        """
         owner = self._owner_ref()
         if owner is not None:
             callbacks = self._hooks.get(name)