New Connection class docstring based on ZODB4 docstring.

trunk/src/ZODB/Connection.py

@@ -13,7 +13,7 @@
 ##############################################################################
 """Database connection support
 
-$Id: Connection.py,v 1.119 2004/02/23 08:23:46 stevea Exp $"""
+$Id: Connection.py,v 1.120 2004/02/24 21:31:03 jeremy Exp $"""
 
 import logging
 import sys
@@ -50,13 +50,35 @@ def resetCaches():
     global_reset_counter += 1
 
 class Connection(ExportImport, object):
-    """Object managers for individual object space.
+    """Connection to ZODB for loading and storing objects.
 
-    An object space is a version of collection of objects.  In a
-    multi-threaded application, each thread gets its own object space.
+    The Connection object serves as a data manager.  The root() method
+    on a Connection returns the root object for the database.  This
+    object and all objects reachable from it are associated with the
+    Connection that loaded them.  When the objects are modified, the
+    Connection is registered with the current transaction.
     
-    The Connection manages movement of objects in and out of object storage.
+    ZODB is organized so that each thread should have its own
+    Connection and that no thread should have more than one Connection
+    to the same database.  A thread is associated with a Connection by
+    loading objects from that Connection.  Objects loaded by one
+    thread should not be used by another thread.
+
+    A Connection can be associated with a single version when it is
+    created.  By default, a Connection is not associated with a
+    version; it uses non-version data.
+
+    Synchronization
+
+    A Connection instance is not thread-safe.  It is designed to
+    support a thread model where each thread has its own transaction.
+    If an application has more than one thread that uses the
+    connection or the transaction the connection is registered with,
+    the application should provide locking.
+
+    $Id: Connection.py,v 1.120 2004/02/24 21:31:03 jeremy Exp $
     """
+
     _tmp = None
     _debug_info = ()
     _opened = None
@@ -464,7 +486,7 @@ class Connection(ExportImport, object):
         """
         assert object._p_jar is self
         # XXX Figure out why this assert causes test failures
-        # assert object._p_oid is not None
+        assert object._p_oid is not None
         self.getTransaction().register(object)
 
     def root(self):