Various clarifications and corrections.

src/ZODB/interfaces.py

@@ -481,9 +481,6 @@ class IStorage(Interface):
         If the transaction had extension items, then these items are
         also included if they don't conflict with the keys above.
         
-        The version argument is provided for backward
-        compatibility. It should always be an empty string.
-        
         """
 
     def isReadOnly():
@@ -534,6 +531,8 @@ class IStorage(Interface):
         - The transaction id of the data record
 
         - The transaction id of the following revision, if any, or None.
+
+        If the object id isn't in the storage, then POSKeyError is raised.
         """
 
     def loadSerial(oid, serial):
@@ -543,6 +542,19 @@ class IStorage(Interface):
         otherwise, POSKeyError is raised.
         """
 
+#     The following two methods are effectively part of the interface,
+#     as they are generally needed when one storage wraps
+#     another. This deserves some thought, at probably debate, before
+#     adding them.
+#
+#     def _lock_acquire():
+#         """Acquire the storage lock
+#         """
+
+#     def _lock_release():
+#         """Release the storage lock
+#         """
+
     def new_oid():
         """Allocate a new object id.
 
@@ -676,7 +688,7 @@ class IStorage(Interface):
         current transaction ends (commits or aborts).
         """
 
-    def tpc_finish(transaction, func = lambda: None):
+    def tpc_finish(transaction, func = lambda tid: None):
         """Finish the transaction, making any transaction changes permanent.
 
         Changes must be made permanent at this point.
@@ -684,6 +696,11 @@ class IStorage(Interface):
         This call is ignored if the storage isn't participating in
         two-phase commit or if it is commiting a different
         transaction.  Failure of this method is extremely serious.
+
+        The second argument is a call-back function that must be
+        called while the storage transaction lock is held.  It takes
+        the new transaction id generated by the transaction.
+        
         """
 
     def tpc_vote(transaction):