Attempt to simplify and highight the differences between IStorage and IMultiCommitStorage

src/ZODB/interfaces.py

@@ -776,12 +776,8 @@ class IStorage(Interface):
         called while the storage transaction lock is held.  It takes
         the new transaction id generated by the transaction.
 
-        The return value must be the committed tid. It is used to set the
-        serial for objects whose ids were passed to previous store calls
-        in the same transaction.
-
-        For compatibility, the return value can also be None, in which case
-        store/tpc_vote must return the serial of stored objects.
+        The return value may be None or the transaction id of the
+        committed transaction, as described in IMultiCommitStorage.
         """
 
     def tpc_vote(transaction):
@@ -797,16 +793,16 @@ class IStorage(Interface):
         without an error, then there must not be an error if
         tpc_finish or tpc_abort is called subsequently.
 
-        The return value can be either None or a sequence of oids for which
-        a conflict was resolved.
-
-        For compatibility, the return value can also be a sequence of object-id
+        The return value can be None or a sequence of object-id
         and serial pairs giving new serials for objects whose ids were
         passed to previous store calls in the same transaction. The serial
         can be the special value ZODB.ConflictResolution.ResolvedSerial to
         indicate that a conflict occurred and that the object should be
         invalidated.
 
+        The return value can also be a sequence of object ids, as
+        described in IMultiCommitStorage.tpc_vote.
+
         After the tpc_vote call, all solved conflicts must have been notified,
         either from tpc_vote or store for objects passed to store.
         """
@@ -814,69 +810,22 @@ class IStorage(Interface):
 class IMultiCommitStorage(IStorage):
     """A multi-commit storage can commit multiple transactions at once.
 
-    It's lilely that future versions of ZODB will require all storages
+    It's likely that future versions of ZODB will require all storages
     to provide this interface.
     """
 
     def store(oid, serial, data, version, transaction):
         """Store data for the object id, oid.
 
-        Arguments:
-
-        oid
-            The object identifier.  This is either a string
-            consisting of 8 nulls or a string previously returned by
-            new_oid.
-
-        serial
-            The serial of the data that was read when the object was
-            loaded from the database.  If the object was created in
-            the current transaction this will be a string consisting
-            of 8 nulls.
-
-        data
-            The data record. This is opaque to the storage.
-
-        version
-            This must be an empty string. It exists for backward compatibility.
-
-        transaction
-            A transaction object.  This should match the current
-            transaction for the storage, set by tpc_begin.
-
-        None is returned.
-
-        Several different exceptions may be raised when an error occurs.
-
-        ConflictError
-          is raised when serial does not match the most recent serial
-          number for object oid and the conflict was not resolved by
-          the storage.
-
-        StorageTransactionError
-          is raised when transaction does not match the current
-          transaction.
-
-        StorageError or, more often, a subclass of it
-          is raised when an internal error occurs while the storage is
-          handling the store() call.
-
+        See IStorage.store. For object's implementing this interface,
+        the return value is always 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.
-
-        This call raises a StorageTransactionError if the storage
-        isn't participating in two-phase commit.  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.
-
-        The return value must be the committed tid. It is used to set the
+        See IStorage.store. For object's implementing this interface,
+        the return value must be the committed tid. It is used to set the
         serial for objects whose ids were passed to previous store calls
         in the same transaction.
         """
@@ -884,17 +833,8 @@ class IMultiCommitStorage(IStorage):
     def tpc_vote(transaction):
         """Provide a storage with an opportunity to veto a transaction
 
-        This call raises a StorageTransactionError if the storage
-        isn't participating in two-phase commit or if it is commiting
-        a different transaction.
-
-        If a transaction can be committed by a storage, then the
-        method should return.  If a transaction cannot be committed,
-        then an exception should be raised.  If this method returns
-        without an error, then there must not be an error if
-        tpc_finish or tpc_abort is called subsequently.
-
-        The return value can be either None or a sequence of oids for which
+        See IStorage.store. For object's implementing this interface,
+        the return value can be either None or a sequence of oids for which
         a conflict was resolved.
         """