add in-line doc that Josh wrote as he was trying to understand this code

diff --git a/src/allmydata/util/observer.py b/src/allmydata/util/observer.py
index 97cfa3f5327c628c3ef69ce7f14fa20afc1e8594..011208166122bd6b969de3c28ffef5269be624d4 100644 (file)
--- a/src/allmydata/util/observer.py
+++ b/src/allmydata/util/observer.py
@@ -3,6 +3,12 @@
 from twisted.internet import defer
 from foolscap.eventual import eventually
 
+"""The idiom we use is for the observed object to offer a method named
+'when_something', which returns a deferred.  That deferred will be fired when
+something happens.  The way this is typically implemented is that the observed
+has an ObserverList whose when_fired method is called in the observed's
+'when_something'."""
+
 class OneShotObserverList:
     """A one-shot event distributor."""
     def __init__(self):