markup glitches

trunk/src/ZODB/DB.py

@@ -13,7 +13,7 @@
 ##############################################################################
 """Database objects
 
-$Id: DB.py,v 1.65 2004/02/27 16:50:02 jeremy Exp $"""
+$Id: DB.py,v 1.66 2004/02/27 22:02:47 jeremy Exp $"""
 
 import cPickle, cStringIO, sys
 from thread import allocate_lock
@@ -296,6 +296,18 @@ class DB(object):
         return m
 
     def close(self):
+        """Close the database and its underlying storage.
+
+        It is important to close the database, because the storage may
+        flush in-memory data structures to disk when it is closed.
+        Leaving the storage open with the process exits can cause the
+        next open to be slow.
+
+        What effect does closing the database have on existing
+        connections?  Technically, they remain open, but their storage
+        is closed, so they stop behaving usefully.  Perhaps close()
+        should also close all the Connections.
+        """
         self._storage.close()
 
     def commitVersion(self, source, destination='', transaction=None):
@@ -541,6 +553,20 @@ class DB(object):
         return self._activity_monitor
 
     def pack(self, t=None, days=0):
+        """Pack the storage, deleting unused object revisions.
+
+        A pack is always performed relative to a particular time, by
+        default the current time.  All object revisions that are not
+        reachable as of the pack time are deleted from the storage.
+
+        The cost of this operation varies by storage, but it is
+        usually an expensive operation.
+
+        @param t: pack time in seconds since the epoch
+        @type t: C{float}
+        @param days: days to subtract from C{t} to compute pack time
+        @type days: C{int}
+        """
         if t is None: t=time()
         t=t-(days*86400)
         try: self._storage.pack(t,referencesf)
@@ -557,6 +583,20 @@ class DB(object):
                 c._cache.cache_size = v
 
     def setClassFactory(self, factory):
+        """Override default mechanism for loading object classes.
+
+        The database stores objects, but uses Python's standard import
+        to load the code for those objects.  The class factory is used
+        by the database serialization layer to find the classes.  It
+        uses L{ZODB.broken.find_global<find_global>} by default.
+
+        This method can be used to override the default class loading
+        code.  See L{ZODB.broken.find_global<find_global>} for details
+        about the contract of C{factory}.
+        
+        @param factory: A class factory for unpickling
+        @type factory: C{function}
+        """
         self._classFactory = factory
 
     def setPoolSize(self, v):
@@ -577,6 +617,22 @@ class DB(object):
     def cacheStatistics(self): return () # :(
 
     def undo(self, id, transaction=None):
+        """Undo a transaction identified by C{id}.
+
+        A transaction can be undone if all of the objects involved in
+        the transaction were not modified subsequently, if any
+        modifications can be resolved by conflict resolution, or if
+        subsequent changes resulted in the same object state.
+
+        The value of C{id} should be generated by calling C{undoLog}
+        or C{undoInfo}.  The value of C{id} is not the same as a
+        transaction id used by other methods; it is unique to C{undo}.
+
+        @param id: a storage-specific transaction identifier
+        @type id: C{string}
+        @param transaction: a transaction context to use
+        @type transaction: C{Transaction}        
+        """
         if transaction is None:
             transaction = get_transaction()
         transaction.register(TransactionalUndo(self, id))