Improve comments.

diff --git a/zookeeper.py b/zookeeper.py
index a1966dcd58258a46a3b12cb4192a09f5aba127bb..39730fa141ced8aff75da0fd4281bb0a29234dff 100644 (file)
--- a/zookeeper.py
+++ b/zookeeper.py
@@ -37,24 +37,26 @@ class RenewableReleasableLease(NonBlockingLease):
     that adds some behaviors:
 
         + Ability to renew the lease if it's already held without
-          going through the effort of reobtaining the same lease.
+          going through the effort of reobtaining the same lease
+          name.
 
         + Ability to release the lease if it's held and not yet
           expired.
 
     It also is more picky than the base class in terms of when it
     evaluates to "True" (indicating that the lease is held); it will
-    begin to evaluate to "False" as soon as the lease has expired
-    even if you use to hold it.  This means client code should be
-    aware that the lease can disappear and it also means that the
-    performance of evaulating the lease requires a round trip to
-    zookeeper every time.
+    begin to evaluate to "False" as soon as the lease has expired even
+    if you used to hold it.  This means client code should be aware
+    that the lease can disappear (expire) while held and it also means
+    that the performance of evaulating the lease (i.e. if lease:)
+    requires a round trip to zookeeper every time.
 
     Note that it is not valid to release the lease more than once
     (since you no longer have it the second time).  The code ignores
-    this.  It's also not possible to reobtain an expired or released
-    lease by calling renew.  Go create a new lease object at that
-    point.
+    the 2nd..nth attempt.  It's also not possible to reobtain an
+    expired or released lease by calling renew.  Go create a new lease
+    object at that point.  Finally, note that when you renew the lease
+    it will evaluate to False briefly as it is reobtained.
 
     """