Improved/added docstrings to support reference documentation on zodb.org

src/ZODB/Connection.py

@@ -78,9 +78,13 @@ def className(obj):
              IPersistentDataManager,
              ISynchronizer)
 class Connection(ExportImport, object):
-    """Connection to ZODB for loading and storing objects."""
-
+    """Connection to ZODB for loading and storing objects.
 
+    Connections manage object state in collaboration with transaction
+    managers.  They're created by calling the
+    :meth:`~ZODB.DB.open` method on :py:class:`database
+    <ZODB.DB>` objects.
+    """
 
     _code_timestamp = 0
 

src/ZODB/DemoStorage.py

@@ -40,10 +40,52 @@ from .utils import load_current, maxtid
         ZODB.interfaces.IStorageIteration,
         )
 class DemoStorage(ConflictResolvingStorage):
+    """A storage that stores changes against a read-only base database
 
+    This storage was originally meant to support distribution of
+    application demonstrations with populated read-only databases (on
+    CDROM) and writable in-memory databases.
+
+    Demo storages are extemely convenient for testing where setup of a
+    base database can be shared by many tests.
+
+    Demo storages are also handy for staging appplications where a
+    read-only snapshot of a production database (often accomplished
+    using a `beforestorage
+    <https://pypi.python.org/pypi/zc.beforestorage>`_) is combined
+    with a changes database implemented with a
+    :class:`~ZODB.FileStorage.FileStorage.FileStorage`.
+    """
 
     def __init__(self, name=None, base=None, changes=None,
                  close_base_on_close=None, close_changes_on_close=None):
+        """Create a demo storage
+
+        :param str name: The storage name used by the
+            :meth:`~ZODB.interfaces.IStorage.getName` and
+            :meth:`~ZODB.interfaces.IStorage.sortKey` methods.
+        :param object base: base storage
+        :param object changes: changes storage
+        :param bool close_base_on_close: A Flag indicating whether the base
+           database should be closed when the demo storage is closed.
+        :param bool close_changes_on_close: A Flag indicating whether the
+           changes database should be closed when the demo storage is closed.
+
+        If a base database isn't provided, a
+        :class:`~ZODB.MappingStorage.MappingStorage` will be
+        constructed and used.
+
+        If ``close_base_on_close`` isn't specified, it will be ``True`` if
+        a base database was provided and ``False`` otherwise.
+
+        If a changes database isn't provided, a
+        :class:`~ZODB.MappingStorage.MappingStorage` will be
+        constructed and used and blob support will be provided using a
+        temporary blob directory.
+
+        If ``close_changes_on_close`` isn't specified, it will be ``True`` if
+        a changes database was provided and ``False`` otherwise.
+        """
 
         if close_base_on_close is None:
             if base is None:
@@ -51,6 +93,8 @@ class DemoStorage(ConflictResolvingStorage):
                 close_base_on_close = False
             else:
                 close_base_on_close = True
+        elif base is None:
+            base = ZODB.MappingStorage.MappingStorage()
 
         self.base = base
         self.close_base_on_close = close_base_on_close
@@ -285,10 +329,17 @@ class DemoStorage(ConflictResolvingStorage):
             raise
 
     def pop(self):
+        """Close the changes database and return the base.
+        """
         self.changes.close()
         return self.base
 
     def push(self, changes=None):
+        """Create a new demo storage using the storage as a base.
+
+        The given changes are used as the changes for the returned
+        storage and ``False`` is passed as ``close_base_on_close``.
+        """
         return self.__class__(base=self, changes=changes,
                               close_base_on_close=False)
 

src/ZODB/FileStorage/FileStorage.py

@@ -140,7 +140,8 @@ class FileStorage(
     ConflictResolvingStorage,
     BaseStorage,
     ):
-
+    """Storage that saves data in a file
+    """
 
     # Set True while a pack is in progress; undo is blocked for the duration.
     _pack_is_in_progress = False
@@ -148,6 +149,82 @@ class FileStorage(
     def __init__(self, file_name, create=False, read_only=False, stop=None,
                  quota=None, pack_gc=True, pack_keep_old=True, packer=None,
                  blob_dir=None):
+        """Create a file storage
+
+        :param str file_name: Path to store data file
+        :param bool create: Flag indicating whether a file should be
+            created even if it already exists.
+        :param bool read_only: Flag indicating whether the file is
+            read only. Only one process is able to open the file
+            non-read-only.
+        :param bytes stop: Time-travel transaction id
+            When the file is opened, data will be read up to the given
+            transaction id.  Transaction ids correspond to times and
+            you can compute transaction ids for a given time using
+            :class:`~ZODB.TimeStamp.TimeStamp`.
+        :param int quota: File-size quota
+        :param bool pack_gc: Flag indicating whether garbage
+            collection should be performed when packing.
+        :param bool pack_keep_old: flag indicating whether old data
+            files should be retained after packing as a ``.old`` file.
+        :param callable packer: An alternative
+           :interface:`packer <ZODB.FileStorage.interfaces.IFileStoragePacker>`.
+        :param str blob_dir: A blob-directory path name.
+           Blobs will be supported if this option is provided.
+
+        A file storage stores data in a single file that behaves like
+        a traditional transaction log. New data records are appended
+        to the end of the file.  Periodically, the file is packed to
+        free up space.  When this is done, current records as of the
+        pack time or later are copied to a new file, which replaces
+        the old file.
+
+        FileStorages keep in-memory indexes mapping object oids to the
+        location of their current records in the file. Back pointers to
+        previous records allow access to non-current records from the
+        current records.
+
+        In addition to the data file, some ancillary files are
+        created. These can be lost without affecting data
+        integrity, however losing the index file may cause extremely
+        slow startup. Each has a name that's a concatenation of the
+        original file and a suffix. The files are listed below by
+        suffix:
+
+        .index
+           Snapshot of the in-memory index.  This are created on
+           shutdown, packing, and after rebuilding an index when one
+           was not found.  For large databases, creating a
+           file-storage object without an index file can take very
+           long because it's necessary to scan the data file to build
+           the index.
+
+        .lock
+           A lock file preventing multiple processes from opening a
+           file storage on non-read-only mode.
+
+        .tmp
+          A file used to store data being committed in the first phase
+          of 2-phase commit
+
+        .index_tmp
+          A temporary file used when saving the in-memory index to
+          avoid overwriting an existing index until a new index has
+          been fully saved.
+
+        .pack
+          A temporary file written while packing containing current
+          records as of and after the pack time.
+
+        .old
+          The previous database file after a pack.
+
+        When the database is packed, current records as of the pack
+        time and later are written to the ``.pack`` file. At the end
+        of packing, the ``.old`` file is removed, if it exists, and
+        the data file is renamed to the ``.old`` file and finally the
+        ``.pack`` file is rewritten to the data file.
+        """
 
         if read_only:
             self._is_read_only = True

src/ZODB/FileStorage/interfaces.py

@@ -16,18 +16,27 @@ import zope.interface
 class IFileStoragePacker(zope.interface.Interface):
 
     def __call__(storage, referencesf, stop, gc):
-        """Pack the file storage into a new file
+        r"""Pack the file storage into a new file
+
+        :param FileStorage storage: The storage object to be packed
+        :param callable referencesf: A function that extracts object
+            references from a pickle bytes string.  This is usually
+            ``ZODB.serialize.referencesf``.
+        :param bytes stop: A transaction id representing the time at
+            which to stop packing.
+        :param bool gc: A flag indicating whether garbage collection
+            should be performed.
 
         The new file will have the same name as the old file with
-        '.pack' appended. (The packer can get the old file name via
+        ``.pack`` appended. (The packer can get the old file name via
         storage._file.name.) If blobs are supported, if the storages
         blob_dir attribute is not None or empty, then a .removed file
-        most be created in the blob directory. This file contains of
-        the form:
+        must be created in the blob directory. This file contains records of
+        the form::
 
            (oid+serial).encode('hex')+'\n'
 
-        or, of the form:
+        or, of the form::
 
            oid.encode('hex')+'\n'
 

src/ZODB/MappingStorage.py

@@ -32,8 +32,22 @@ import zope.interface
         ZODB.interfaces.IStorageIteration,
         )
 class MappingStorage(object):
+    """In-memory storage implementation
+
+    Note that this implementation is somewhat naive and inefficient
+    with regard to locking.  It's implementation is primarily meant to
+    be a simple illustration of storage implementation. It's also
+    useful for testing and exploration where scalability and efficiency
+    are unimportant.
+    """
 
     def __init__(self, name='MappingStorage'):
+        """Create a mapping storage
+
+        The name parameter is used by the
+        :meth:`~ZODB.interfaces.IStorage.getName` and
+        :meth:`~ZODB.interfaces.IStorage.sortKey` methods.
+        """
         self.__name__ = name
         self._data = {}                               # {oid->{tid->pickle}}
         self._transactions = BTrees.OOBTree.OOBTree() # {tid->TransactionRecord}

src/ZODB/interfaces.py

@@ -437,7 +437,6 @@ class IStorage(Interface):
     """A storage is responsible for storing and retrieving data of objects.
 
     Consistency and locking
-    -----------------------
 
     When transactions are committed, a storage assigns monotonically
     increasing transaction identifiers (tids) to the transactions and
@@ -472,6 +471,9 @@ class IStorage(Interface):
 
         Finalize the storage, releasing any external resources.  The
         storage should not be used after this method is called.
+
+        Note that daabses close theor storages when they're closed, so
+        this method isn't generally called from application code.
         """
 
     def getName():