From 80b09b6d5438128c08a7799dd1cac43cd183bf45 Mon Sep 17 00:00:00 2001
From: Zooko O'Whielacronx <zooko@zooko.com>
Date: Wed, 23 May 2007 15:11:23 -0700
Subject: [PATCH] add in-line doc that Josh wrote as he was trying to
 understand this code

---
 src/allmydata/util/observer.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/allmydata/util/observer.py b/src/allmydata/util/observer.py
index 97cfa3f5..01120816 100644
--- 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):
-- 
2.45.2